@floatonnear/mcp 0.10.1 → 0.10.3

package/dist/server.js

@@ -56,13 +56,14 @@ import { z } from "zod";
 import { fromBaseUnits, humaniseTreeNode, toBaseUnits } from "./amounts.js";
 import { DEFAULT_GAS_TGAS, planAddNode, planAddRole, planBindVirtualAgent, planUnbindVirtualAgent, planFreezeNode, planPurgeSettled, planSetCooldown, planSetNodeCaps, planSetPaused, planSetRecipients, planSetStrictAllocation, toCliCommand, planSetApprovalThreshold, planApprovePayment, planRejectPayment, planWithdraw, } from "./payloads.js";
 import { accountExists, rpcForNetwork, RPC_BY_NETWORK, newRequestId, requireAgentKey, viewAccessKeys, viewAccount, viewFunction, } from "./rpc.js";
-import { AGENT_NODE_ID, generateAgentKey } from "./agent-key.js";
+import { AGENT_NODE_ID, generateAgentKey, retireRole } from "./agent-key.js";
 import { resolveKeySource } from "./key-file.js";
 import { dirname, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { listAgents, listRoles, selectRole } from "./roles.js";
-import { label as tokenLabel, tokenMeta } from "./token-meta.js";
+import { listAgents, listUnloadable, selectRole } from "./roles.js";
+import { resolveKeyringPath } from "./keyring-path.js";
+import { displaySymbol, label as tokenLabel, tokenMeta } from "./token-meta.js";
 /**
  * A decimal NEAR string to yoctoNEAR, without floating point.
  *
@@ -77,7 +78,7 @@ function toYoctoNear(n) {
 }
 import { buildCreatePlan, FACTORY_BY_NETWORK } from "./create.js";
 import { buildRoute, sendRequestPayment } from "./sign.js";
-import { explainOutcome } from "./explain.js";
+import { explainOutcome, planVoice } from "./explain.js";
 import { getQuote, signBinding, toBase64 } from "./quote.js";
 /** How long a quote stays valid. Long enough to sign and send, short
  *  enough that a stale price is not honoured. */
@@ -157,6 +158,25 @@ if (!Object.hasOwn(RPC_BY_NETWORK, NETWORK)) {
         `questions about the wrong chain.`);
     process.exit(1);
 }
+/**
+ * A syntactically valid ed25519 key used ONLY to dry-run payload construction.
+ *
+ * `planAddRole` needs a public key to build args, and we want its exceptions
+ * BEFORE generating a real one. All zeroes in base58 is "1" repeated, which
+ * parses as a key and is obviously not anyone's.
+ */
+/**
+ * Resolved ONCE, at startup, from the environment — never recomputed, so the
+ * path cannot change mid-session if something alters the working directory.
+ *
+ * The vault id is read straight from the env rather than from `cfg`, because
+ * `cfg` is what this feeds.
+ */
+const KEYRING = resolveKeyringPath({
+    explicit: process.env.NEAR_VAULT_AGENT_KEYS,
+    vault: process.env.NEAR_VAULT_CONTRACT,
+});
+const PLACEHOLDER_PUBLIC_KEY = `ed25519:${"1".repeat(44)}`;
 const cfg = {
     vault: process.env.NEAR_VAULT_CONTRACT ?? "",
     /**
@@ -220,10 +240,17 @@ const cfg = {
     // Guarded by `scripts/check-create-page.mjs`, which fetches the real link
     // shape, follows redirects, and checks the wasm at the landing origin.
     appUrl: process.env.NEAR_VAULT_APP_URL ?? "https://usefloat.xyz",
-    // The fleet keyring. Same default and same file the adapter reads — two
-    // readers disagreeing about where credentials live is how an agent ends up
-    // "configured" and unreachable.
-    agentKeysPath: process.env.NEAR_VAULT_AGENT_KEYS ?? ".float/agent-keys.json",
+    // The fleet keyring. Same file the adapter reads — two readers disagreeing
+    // about where credentials live is how an agent ends up "configured" and
+    // unreachable.
+    //
+    // RESOLVED, NOT DEFAULTED. This was the bare relative string
+    // `.float/agent-keys.json`, which Node resolves against the server's CWD —
+    // i.e. wherever the CLIENT happened to be launched. One server entry in
+    // `~/.claude.json` therefore meant a DIFFERENT keyring per directory, and a
+    // key written from one project was invisible from another. See
+    // `keyring-path.ts` for the resolution rule and the measurement.
+    agentKeysPath: KEYRING.path,
 };
 /**
  * NO VAULT IS THE COMMONEST STATE, SO THE MESSAGE HAS TO BE AN ONRAMP.
@@ -269,12 +296,65 @@ function tokenFor(t) {
 }
 const text = (s) => ({ content: [{ type: "text", text: s }] });
 const json = (v) => text(JSON.stringify(v, null, 2));
-/** Payload + summary + warnings + a runnable command, so approving needs no trust in this server. */
-function renderPlan(p) {
+/**
+ * Payload + summary + warnings + a runnable command, so approving needs no
+ * trust in this server — fronted by the plain-English fields.
+ *
+ * THE UX FIELDS COME FIRST, AND THEY ARE THE SAME THREE `vault_pay` RETURNS.
+ * This used to return five technical keys and no sentence, so agents described
+ * the mechanism — "returns an unsigned payload; the server does not sign; run
+ * `near contract call-function`…" — to someone who had asked to raise a limit.
+ * One shape across every tool means the instruction can be one sentence:
+ * relay `say`, add `next_step`, stop.
+ *
+ * `money_moved` is ALWAYS false here, and that is not a technicality worth
+ * hiding: a plan is a proposal. Nothing has moved, nothing has changed, and an
+ * agent that reports otherwise has lied about state the user is about to be
+ * asked to change themselves.
+ *
+ * `unsigned_payload` stays TOP-LEVEL rather than moving under `technical`:
+ * `scripts/check-mcp-live.mjs` asserts on it against the real server, and
+ * quietly renaming the key it reads would turn a live check green-by-absence.
+ */
+async function renderPlan(p) {
+    const voice = planVoice(p);
+    /**
+     * SWAP TOKEN IDS FOR SYMBOLS IN THE SENTENCE ONLY.
+     *
+     * `summary` is built in `payloads.ts`, which is pure and has no network — so
+     * it prints the token's ACCOUNT ID. For mainnet USDC that is 64 hex
+     * characters, and `planVoice` reuses the summary verbatim, so the sentence
+     * read: 'Create budget node "research" as the ROOT with
+     * 17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1: 5/day'.
+     *
+     * Resolving here rather than in `payloads.ts` keeps that module pure and
+     * synchronously testable, which is worth more than saving this substitution.
+     * `technical.summary` is left EXACT — the id is the useful form there.
+     *
+     * Only the `say` is rewritten, and only for ids actually present, so a
+     * payload with no tokens costs nothing.
+     */
+    let say = voice.say;
+    const ids = [
+        ...new Set((Array.isArray(p.args.limits) ? p.args.limits : [])
+            .map((l) => l?.token)
+            .filter((t) => typeof t === "string" && say.includes(t))),
+    ];
+    if (ids.length > 0) {
+        const metas = await metaFor(ids);
+        for (const id of ids) {
+            const sym = metas.get(id)?.symbol;
+            // Substituted ONLY when a symbol actually resolved. Falling back to
+            // "tokens" here would erase which token a limit applies to, and a
+            // multi-token payload would become ambiguous.
+            if (sym)
+                say = say.split(id).join(sym);
+        }
+    }
     return json({
-        action: p.methodName,
-        summary: p.summary,
-        warnings: p.warnings,
+        say,
+        next_step: voice.next,
+        money_moved: false,
         unsigned_payload: {
             receiver_id: p.receiverId,
             method_name: p.methodName,
@@ -282,6 +362,11 @@ function renderPlan(p) {
             gas_tgas: p.gasTgas,
             deposit_yocto: p.depositYocto,
         },
+        technical: {
+            action: p.methodName,
+            summary: p.summary,
+            warnings: p.warnings,
+        },
         approve_with: toCliCommand(p, cfg.network),
         note: "This server did NOT sign this. Review the summary, then run the command " +
             "or approve the payload in your wallet.",
@@ -381,7 +466,7 @@ WORTH KNOWING
   An implicit account (a 64-character hex id) cannot own a vault at all. Tell the user to use a
   named account rather than retrying.
   Amounts are whole tokens in these tools (1.5 means 1.5 USDC), never base units.`;
-const server = new McpServer({ name: "float", version: "0.10.0" }, { instructions: INSTRUCTIONS });
+const server = new McpServer({ name: "float", version: "0.10.3" }, { instructions: INSTRUCTIONS });
 /**
  * THE FULL OPERATING GUIDE, AS AN MCP RESOURCE.
  *
@@ -579,6 +664,11 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
     }
     if (config.owner !== owner) {
         return json({
+            say: `That vault address already belongs to someone else, so it is not yours to use. ` +
+                `Nothing was changed. I can set one up for you under a different name instead — ` +
+                `want me to?`,
+            next_step: `Say the word and I'll create a vault under a label, on a different address.`,
+            money_moved: false,
             status: "NOT_YOURS",
             vault: target,
             actualOwner: config.owner,
@@ -588,16 +678,116 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
                 `under a label instead, which lands on a different address.`,
         });
     }
+    /**
+     * WHAT ACTUALLY STOPS THIS VAULT PAYING, read from the chain.
+     *
+     * The old `nextSteps` were a FIXED list ending "nothing can spend from it
+     * until an agent is bound — vault_add_role". For a vault created with
+     * `bindAgent` that is simply false: the agent is already bound, and the
+     * real gate is that the vault holds no tokens. Measured 2026-11-13 — the
+     * agent relaying it had to correct the tool in front of the user.
+     *
+     * Worse, nothing told the owner HOW to fund it, or that funding is a plain
+     * wallet send to an address, or what that address is. This is the moment
+     * they need it: they have just signed, they are looking at the result, and
+     * the next thing standing between them and a working vault is money.
+     *
+     * So the steps are derived from live state instead of asserted. Three
+     * reads, once, on a path that runs once per vault.
+     */
+    const rootToken = await (async () => {
+        // THE TREE IS AUTHORITATIVE, not cfg.token: at creation time
+        // NEAR_VAULT_CONTRACT is typically unset, so the configured token may be
+        // empty while the vault plainly names one in its root limits.
+        const tree = await viewFunction(rpc, target, "get_tree", {}).catch(() => null);
+        return tree?.find((n) => n.id === 0)?.limits?.[0]?.token;
+    })();
+    const meta = rootToken
+        ? await tokenMeta(rpc, rootToken, (r, t) => viewFunction(r, t, "ft_metadata", {})).catch(() => null)
+        : null;
+    const symbol = meta?.symbol ?? "the token";
+    const [held, registered, agentKeys] = await Promise.all([
+        rootToken
+            ? viewFunction(rpc, rootToken, "ft_balance_of", { account_id: target }).catch(() => null)
+            : Promise.resolve(null),
+        rootToken
+            ? viewFunction(rpc, rootToken, "storage_balance_of", {
+                account_id: target,
+            }).catch(() => undefined)
+            : Promise.resolve(undefined),
+        viewAccessKeys(rpc, target)
+            // Narrowed the same way vault_gas does: `permission` is a union and
+            // only the gas-key arm carries this field.
+            .then((ks) => ks.filter((k) => k.access_key?.permission
+            ?.GasKeyFunctionCall !== undefined).length)
+            .catch(() => null),
+    ]);
+    const empty = held !== null && BigInt(held) === 0n;
+    const funding = {
+        token: rootToken ?? null,
+        symbol: rootToken ? symbol : null,
+        balance: held === null ? null : fromBaseUnits(BigInt(held), meta?.decimals ?? cfg.decimals),
+        /** `undefined` = could not read; `null` = read and NOT registered. */
+        registeredOnToken: registered === undefined ? null : registered !== null,
+        sendTo: target,
+        howTo: `Funding is a plain send from the owner's own wallet: send ${symbol} to ${target}. ` +
+            `This server cannot do it — the agent key cannot touch a token contract, which is the ` +
+            `point of the product.`,
+    };
+    const nextSteps = [
+        `Set NEAR_VAULT_CONTRACT=${target} so every other tool reads this vault.`,
+    ];
+    /**
+     * UNREGISTERED IS NAMED FIRST, because it is the one that makes a transfer
+     * FAIL rather than merely be impossible. Vaults created before the factory
+     * registered them are still in this state; the fix is forward-only.
+     */
+    if (registered === null) {
+        nextSteps.push(`REGISTER IT FIRST: ${target} is not registered on ${rootToken}, and a transfer to an ` +
+            `unregistered account FAILS. The owner must call storage_deposit on the token with ` +
+            `about 0.00125 NEAR attached and registration_only: true. Vaults created through the ` +
+            `current factory are registered automatically; this one was not.`);
+    }
+    if (empty) {
+        nextSteps.push(`FUND IT: the vault holds no ${symbol}. Tell the owner to send ${symbol} to ${target} ` +
+            `from their own wallet, and ASK how much they want to move. Nothing can be paid out ` +
+            `until it has a balance — the budget caps what MAY be spent, not what exists.`);
+    }
+    if (agentKeys === 0) {
+        nextSteps.push(`No agent is bound yet, so nothing can authorise a payment — vault_add_role.`);
+    }
+    if (!empty && agentKeys !== 0 && registered !== null) {
+        nextSteps.push(`Ready. vault_budget shows today's allowance; vault_pay makes a payment.`);
+    }
+    else {
+        nextSteps.push(`vault_tree shows the budget shape; vault_budget shows what is left today.`);
+    }
+    /**
+     * "LIVE" PLUS A CONFIG DUMP IS NOT AN ANSWER TO "did it work?".
+     *
+     * `funding` and `nextSteps` already hold everything a person needs; what
+     * was missing was the one sentence that orders them. The empty-vault case
+     * is the one that matters: a vault that exists but holds nothing cannot
+     * pay, and "LIVE" on its own reads as done.
+     */
+    const liveSay = empty
+        ? `Your vault is set up and ready. It has no money in it yet, so add funds to it and ` +
+            `then I can start paying from it.`
+        : agentKeys === 0
+            ? `Your vault is set up and funded. One thing left: it needs an agent budget before ` +
+                `anything can be paid from it.`
+            : `Your vault is live, funded, and has an agent that can pay within its limits. ` +
+                `Nothing else to do.`;
     return json({
+        say: liveSay,
+        next_step: nextSteps[0] ?? null,
+        money_moved: false,
         status: "LIVE",
         vault: target,
         owner: config.owner,
         config,
-        nextSteps: [
-            `Set NEAR_VAULT_CONTRACT=${target} so every other tool reads this vault.`,
-            `vault_tree shows the budget; vault_budget shows what is left today.`,
-            `Nothing can spend from it until an agent is bound with a budget — vault_add_role.`,
-        ],
+        funding,
+        nextSteps,
     });
 });
 /**
@@ -688,7 +878,33 @@ server.tool("vault_budget", "Read one node's budget for a UTC day: cap, executed
     const tok = tokenFor(token);
     const meta = (await metaFor([tok])).get(tok) ?? null;
     const d = meta?.decimals ?? cfg.decimals;
+    // The SYMBOL for the sentence; the full `SYMBOL (id)` label stays on the
+    // `token` field below, where the id is useful rather than alarming.
+    const sym = displaySymbol(meta);
+    const cap = fromBaseUnits(BigInt(b.daily_cap), d);
+    const used = fromBaseUnits(BigInt(b.executed), d);
+    const left = fromBaseUnits(BigInt(b.available), d);
+    const inFlight = fromBaseUnits(BigInt(b.pending), d);
+    /**
+     * A BUDGET READ IS THE COMMONEST QUESTION A PERSON ASKS, and it was
+     * answered with eight fields and no sentence — including `day: 20768`.
+     * "Today: 0.25 of 25 USDC used, 24.75 left" is the same facts in the order
+     * someone asked for them.
+     *
+     * `pending` is mentioned ONLY when it is non-zero. It is in-flight money —
+     * reserved, not yet settled — and naming it on every read invites the
+     * question "what's pending?" when the answer is almost always "nothing".
+     * But when it IS non-zero, leaving it out makes the arithmetic look wrong:
+     * cap minus used would not equal what is left.
+     */
+    const pendingNote = BigInt(b.pending) > 0n ? ` ${inFlight} ${sym} is still in flight.` : "";
     return json({
+        say: `Today: ${used} of ${cap} ${sym} used, ${left} ${sym} left.${pendingNote}` +
+            ` Resets at midnight UTC.`,
+        next_step: null,
+        // A read moves nothing. Stated rather than omitted so the field means the
+        // same thing on every tool that has it.
+        money_moved: false,
         node_id: nodeId,
         token: tokenLabel(tok, meta),
         /**
@@ -703,10 +919,10 @@ server.tool("vault_budget", "Read one node's budget for a UTC day: cap, executed
         date: new Date(Number(b.day) * 86_400_000).toISOString().slice(0, 10),
         day: b.day,
         resets: "00:00 UTC",
-        daily_cap: fromBaseUnits(BigInt(b.daily_cap), d),
-        executed: fromBaseUnits(BigInt(b.executed), d),
-        pending: fromBaseUnits(BigInt(b.pending), d),
-        available: fromBaseUnits(BigInt(b.available), d),
+        daily_cap: cap,
+        executed: used,
+        pending: inFlight,
+        available: left,
     });
 });
 /**
@@ -907,33 +1123,135 @@ server.tool("vault_add_role", "Add a NEW departmental agent to an existing vault
         .describe("NEAR for the agent's gas key. Default 0.12 (~160 payments measured). Minimum 0.06, because NEAR reserves prepaid gas up front."),
 }, async ({ role, dailyCap, perTxCap, recipients, token, cooldownSec, fundingNear }) => {
     const vault = requireVault();
-    // REFUSE A DUPLICATE ROLE BEFORE GENERATING A KEY. The contract would
-    // happily create a second node with the same label, and the keyring would
-    // index only the last one — so the first agent would still be bound and
-    // funded on chain while becoming unreachable locally.
-    if (listRoles(cfg).some((r) => r.role === role)) {
-        return text(`This vault already has an agent with the role '${role}'. Roles index the ` +
-            `keyring, so a second one would hide the first — which would stay bound and ` +
-            `funded on chain with nothing able to select it. Pick another name, or use ` +
-            `the existing agent.`);
+    /**
+     * A DUPLICATE ROLE IS REFUSED — BUT "IN THE KEYRING" IS NOT "ALIVE".
+     *
+     * The contract would happily create a second node with the same label, and
+     * `selectRole` resolves with `find`, so the FIRST entry wins forever: the
+     * older agent would stay bound and funded on chain with nothing able to
+     * select it. That part of the old guard was right.
+     *
+     * What was wrong was treating a keyring entry as proof an agent exists. A
+     * `vault_add_role` that writes a key and then fails to land on chain leaves
+     * an ORPHAN — a role bound to nothing, no node, no gas key — and this guard
+     * then refused the user's own retry, citing the wreckage of the attempt
+     * that failed thirty seconds earlier. Reported 2026-11-13 for a `travel`
+     * agent; the user had to go and find the file by hand.
+     *
+     * So ask the CHAIN, which is the only thing that knows:
+     *   bound to a node -> a real agent. Refuse, as before.
+     *   not bound       -> an orphan. Retire it and carry on.
+     *   chain unreachable or no recorded key -> cannot tell. Refuse, and SAY
+     *                      it is a "cannot tell", not a "there is one".
+     */
+    let retired = null;
+    const clash = listAgents(cfg).find((a) => a.role === role);
+    if (clash) {
+        const boundNode = clash.publicKey
+            ? await viewFunction(cfg.rpcUrl, vault, "get_virtual_agent_node", {
+                public_key: clash.publicKey,
+            }).catch(() => undefined)
+            : undefined;
+        if (boundNode === undefined) {
+            return text(`There is already a key filed under the role '${role}' for this vault, and I could not ` +
+                `confirm with ${vault} whether it is a working agent — ` +
+                `${clash.publicKey ? "the network read failed" : "that entry predates recorded public keys"}. ` +
+                `Refusing rather than guessing: adding a second '${role}' would permanently hide ` +
+                `whichever was filed first, and if the existing one IS bound and funded, nothing ` +
+                `would be able to select it again. Try vault_roles to see the fleet, or pick ` +
+                `another name.`);
+        }
+        if (boundNode !== null) {
+            return text(`This vault already has a working agent with the role '${role}' — it is bound to ` +
+                `node ${boundNode}. A second one would hide it, and it would stay funded on chain ` +
+                `with nothing able to select it. Pick another name, or just use the existing agent.`);
+        }
+        /**
+         * ORPHAN. The chain says this key is bound to nothing, so it cannot be
+         * anyone's working agent. Its name is taken off it — the secret stays on
+         * disk, see `retireRole` — and the request proceeds, which is what the
+         * user asked for in the first place.
+         */
+        retired = retireRole({
+            keyringPath: cfg.agentKeysPath,
+            vault,
+            publicKey: clash.publicKey,
+        });
     }
+    /**
+     * VALIDATE EVERYTHING BEFORE A KEY TOUCHES DISK.
+     *
+     * This used to generate and WRITE the agent's key, and only then build the
+     * payload — which calls `tokenFor()` and the amount conversions, any of
+     * which can throw. So a call that failed validation left a real keypair
+     * filed under the role name, bound to nothing: no node, no gas key. The
+     * user's retry then hit "this vault already has an agent with the role
+     * 'travel'" and was blocked by the wreckage of their own failed attempt.
+     *
+     * Measured 2026-11-13: a `vault_add_role` that failed on a missing token
+     * wrote `travel` to the keyring 55 seconds before the retry was refused.
+     *
+     * Everything that can throw now runs FIRST, against a throwaway public key,
+     * so a failure writes nothing at all. The key is generated only once the
+     * payload is known to be buildable.
+     */
     const fundingYocto = toYoctoNear(fundingNear ?? "0.12");
-    // `nodeId: null` — NOT YET KNOWN. `add_role` creates the node inside the
-    // contract, so its id does not exist until the transaction lands.
+    let limits;
+    try {
+        limits = [{ token: tokenFor(token), dailyCap, perTxCap, decimals: cfg.decimals }];
+        // Build it once with a placeholder to force every conversion and check
+        // to run. Nothing is kept; this is a dry run for its exceptions.
+        planAddRole(vault, role, limits, cooldownSec ?? 0, recipients ?? null, PLACEHOLDER_PUBLIC_KEY, fundingYocto);
+    }
+    catch (e) {
+        return text(`${String(e.message)}${String.fromCharCode(10)}${String.fromCharCode(10)}` +
+            `Nothing was written — no key was generated, so '${role}' is still free to use once ` +
+            `this is corrected.`);
+    }
+    // Only now. `nodeId: null` — NOT YET KNOWN: `add_role` creates the node
+    // inside the contract, so its id does not exist until the transaction lands.
     const generated = generateAgentKey({
         vault,
-        dir: dirname(cfg.agentKeysPath),
+        // The FULL configured path, not its directory. Passing the directory
+        // discarded the filename, so a keyring pinned to anything other than
+        // `agent-keys.json` was read from one file and written to another.
+        keyringPath: cfg.agentKeysPath,
         role,
         nodeId: null,
     });
-    let payload;
-    try {
-        payload = planAddRole(vault, role, [{ token: tokenFor(token), dailyCap, perTxCap, decimals: cfg.decimals }], cooldownSec ?? 0, recipients ?? null, generated.publicKey, fundingYocto);
-    }
-    catch (e) {
-        return text(String(e.message));
-    }
+    const payload = planAddRole(vault, role, limits, cooldownSec ?? 0, recipients ?? null, generated.publicKey, fundingYocto);
+    /**
+     * THE SENTENCE FOR THE MOMENT THIS TOOL IS USED.
+     *
+     * This returned a public key, a keyring path, a payload and two warnings —
+     * and agents duly reported "generated an ed25519 keypair, wrote it to the
+     * keyring; the 0.12 NEAR deposit funds a NEP-611 gas key" to someone who
+     * had asked for a news agent with a small budget.
+     *
+     * What the person needs is the BUDGET, in the units they named, and that
+     * one approval stands between them and it. The key, the path and the
+     * funding mechanics are real and stay in the payload for the agent.
+     *
+     * The caps are re-stated from the ARGUMENTS rather than the built payload,
+     * because the payload holds base units and the caller spoke in tokens.
+     */
+    /**
+     * RESOLVE THE SYMBOL. Passing `null` metadata here printed the token's
+     * ACCOUNT ID in the sentence — "1 usdc.testnet a day", and on mainnet a
+     * 64-character hex string. One cached view call, and it degrades to
+     * "tokens" rather than to an id when the chain cannot be reached, which
+     * keeps this tool usable offline.
+     */
+    const roleMeta = await tokenMeta(cfg.rpcUrl, tokenFor(token), (rpc, t) => viewFunction(rpc, t, "ft_metadata", {})).catch(() => null);
+    const roleSay = `I'll set up a ${role} budget: ${dailyCap} ${displaySymbol(roleMeta)} a day, and no ` +
+        `single payment over ${perTxCap}. You approve it once in your wallet, and after that ` +
+        `I can pay within those limits — I can't raise them myself. Nothing has changed yet.`;
     return json({
+        say: roleSay,
+        next_step: `Approve it in your wallet, then tell me and I'll confirm the ${role} budget is live.`,
+        // The approval moves 0.12 NEAR into the agent's gas key when signed, but
+        // NOTHING has moved at this point — this is an unsigned proposal.
+        money_moved: false,
         role,
         agent: {
             publicKey: generated.publicKey,
@@ -946,30 +1264,165 @@ server.tool("vault_add_role", "Add a NEW departmental agent to an existing vault
                 `credential is filed under the ROLE, so vault_pay({role:"${role}"}) works ` +
                 `without it.`,
         ],
+        // Only present when something was actually cleaned up, so the ordinary
+        // case stays quiet. An orphan silently replaced would be the same
+        // invisible-state problem in a new costume.
+        ...(retired
+            ? {
+                replaced: `A key was already filed under '${role}' but ${vault} reports it bound to ` +
+                    `nothing — a leftover from an earlier attempt that never landed on chain. It has ` +
+                    `been renamed '${retired.retiredTo}' so it cannot shadow this one. Its secret ` +
+                    `was NOT deleted.`,
+            }
+            : {}),
         warnings: [
             `Show the owner this public key and have them confirm it before signing: ${generated.publicKey}`,
             `The private key is at ${generated.keyringPath}. Do not print it.`,
+            // A second keyring holding keys for THIS vault means roles this server
+            // cannot see. Said here rather than left to surface later as "my agent
+            // vanished".
+            ...(KEYRING.alsoFound.length
+                ? [
+                    `Another keyring also holds keys for this vault and is NOT being read: ` +
+                        `${KEYRING.alsoFound.join(", ")}. This one was chosen. Set ` +
+                        `NEAR_VAULT_AGENT_KEYS to pin one deliberately.`,
+                ]
+                : []),
         ],
     });
 });
-server.tool("vault_roles", "List the agents this server can sign as, by role. Use it before vault_pay when a vault has more than one agent — the signing key decides which budget is charged. No key material is returned.", {}, async () => json(
-// `listAgents`, NOT `listRoles`. The latter filters to entries carrying a
-// role, which is correct for SELECTION and wrong for REPORTING: a
-// creation-time agent from `bindAgent` has no role, so a working vault
-// with a funded gas key reported `[]` — indistinguishable from having no
-// agent at all, and the obvious next move is then the wrong one.
-listAgents(cfg).map((r) => ({
-    role: r.role,
-    nodeId: r.nodeId,
-    agentId: r.agentId,
-    ...(r.role === null
-        ? {
-            note: "No role name — created by vault_create({bindAgent:true}), which does not " +
-                "name one. It can still sign; vault_pay selects it by nodeId or as the only " +
-                "credential. Give it a name with vault_add_role if you want several agents.",
+server.tool("vault_roles", "List the agents this server can sign as, CROSS-CHECKED against the vault. Says which keys are actually installed and which are dead. Use it before vault_pay when a vault has more than one agent — the signing key decides which budget is charged. No key material is returned.", {}, async () => {
+    const vault = requireVault();
+    /**
+     * THE KEYRING IS A CLAIM. THE CHAIN IS THE FACT.
+     *
+     * This used to report `listAgents(cfg)` verbatim — role, nodeId and all —
+     * straight out of the local file, without ever asking the vault whether it
+     * had heard of those keys. So a keyring pointing at the wrong directory
+     * reported a healthy, signable agent on node 1 that the vault had never
+     * been told about, and `vault_pay` then signed with it and came back
+     * NOT_VIRTUAL_AGENT.
+     *
+     * Measured 2026-11-13: that cost a user a whole session of forensics —
+     * reading .claude.json by hand, diffing two keyring files, checking gas
+     * balances — to find a single wrong path. The tool whose entire job is
+     * "which agents can I sign as" was the one reporting the false positive,
+     * which is why nothing caught it earlier.
+     *
+     * So every entry is now resolved against the vault:
+     *   get_virtual_agent_node(pk)  -> the node the CHAIN binds it to, or null
+     *   the access-key list         -> is a funded gas key actually installed
+     *
+     * And the INVERSE is reported too: a gas key on the vault that is not in
+     * the keyring is an agent you cannot sign as. Both directions of the
+     * disagreement matter, and only one of them was ever visible.
+     */
+    const local = listAgents(cfg);
+    const onChainKeys = await viewAccessKeys(cfg.rpcUrl, vault)
+        .then((ks) => ks
+        .map((k) => ({
+        publicKey: k.public_key,
+        gas: k.access_key?.permission?.GasKeyFunctionCall,
+    }))
+        .filter((k) => k.gas !== undefined))
+        .catch(() => null);
+    const resolved = await Promise.all(local.map(async (r) => {
+        if (!r.publicKey) {
+            return {
+                role: r.role,
+                agentId: r.agentId,
+                status: "UNVERIFIABLE",
+                detail: "This keyring entry has no public key recorded, so the chain cannot be asked " +
+                    "about it. It predates the field. Re-create the agent with vault_add_role.",
+            };
         }
-        : {}),
-}))));
+        const node = await viewFunction(cfg.rpcUrl, vault, "get_virtual_agent_node", {
+            public_key: r.publicKey,
+        }).catch(() => undefined);
+        const installed = onChainKeys?.find((k) => k.publicKey === r.publicKey);
+        const balance = installed?.gas?.balance;
+        if (node === undefined) {
+            return { role: r.role, agentId: r.agentId, status: "UNKNOWN", detail: "could not reach the chain" };
+        }
+        if (node === null) {
+            return {
+                role: r.role,
+                agentId: r.agentId,
+                publicKey: r.publicKey,
+                status: "DEAD",
+                detail: `This key is NOT bound on ${vault}. Signing with it returns NOT_VIRTUAL_AGENT. ` +
+                    `It is a key for a different vault, or left over from one that was torn down, or ` +
+                    `this client is reading the wrong keyring. Do NOT use it; vault_add_role creates ` +
+                    `one the vault will accept.`,
+            };
+        }
+        return {
+            role: r.role,
+            agentId: r.agentId,
+            nodeId: node,
+            // The LOCAL nodeId is reported only when it disagrees, because a
+            // disagreement means the file is stale and that is worth saying.
+            ...(r.nodeId !== undefined && r.nodeId !== node
+                ? { staleLocalNodeId: r.nodeId, note: "the keyring records a different node; the chain wins" }
+                : {}),
+            status: installed ? "USABLE" : "BOUND_BUT_NO_GAS_KEY",
+            gasNear: balance ? fromBaseUnits(BigInt(balance), 24) : null,
+            ...(installed
+                ? {}
+                : {
+                    detail: "Bound to a node, so it may AUTHORISE a payment, but no gas key is installed " +
+                        "on the vault, so it cannot SUBMIT one. float-agent installs and funds it.",
+                }),
+        };
+    }));
+    const heldKeys = new Set(local.map((r) => r.publicKey).filter(Boolean));
+    const unheld = (onChainKeys ?? [])
+        .filter((k) => !heldKeys.has(k.publicKey))
+        .map((k) => ({
+        publicKey: k.publicKey,
+        status: "ON_CHAIN_BUT_NO_LOCAL_KEY",
+        detail: "The vault has this agent installed, but this client does not hold its private key, " +
+            "so it cannot sign as it. It belongs to another machine or another client.",
+    }));
+    const unloadable = listUnloadable(cfg);
+    const usable = resolved.filter((r) => r.status === "USABLE").length;
+    return json({
+        vault,
+        usable,
+        /**
+         * WHICH FILE THIS ANSWER CAME FROM.
+         *
+         * Every status below is a claim about credentials in one specific file,
+         * and that file is CHOSEN (see `keyring-path.ts`) — so an answer that
+         * does not name it cannot be checked. Omitting it is what turned "my
+         * travel agent is missing" into a session of hand-diffing keyrings:
+         * the tool had the path and did not say it.
+         */
+        keyring: {
+            path: cfg.agentKeysPath,
+            chosenBecause: KEYRING.why,
+            ...(KEYRING.alsoFound.length
+                ? {
+                    NOT_being_read: KEYRING.alsoFound,
+                    warning: `Another keyring also holds keys for this vault. Agents filed there will NOT ` +
+                        `appear above. Set NEAR_VAULT_AGENT_KEYS to pin one deliberately.`,
+                }
+                : {}),
+        },
+        agents: resolved,
+        ...(unheld.length ? { onChainWithoutLocalKey: unheld } : {}),
+        // Entries the loader refuses to read. Reported rather than dropped, so
+        // "I have a key but this shows nothing" is answerable.
+        ...(unloadable.length ? { unreadableKeyringEntries: unloadable } : {}),
+        ...(usable === 0
+            ? {
+                warning: `NO USABLE AGENT. vault_pay cannot succeed against ${vault} from this client. ` +
+                    `Every entry above is dead, unbound, or missing its gas key — the commonest cause ` +
+                    `is NEAR_VAULT_AGENT_KEYS pointing at a keyring for a different vault.`,
+            }
+            : {}),
+    });
+});
 // ------------------------------------------------------------- onboarding
 server.tool("vault_create", "For a user who has NO vault yet. Works out where their vault will live, exactly what it costs to create, and returns a URL they approve in their own wallet. Needs no key and no existing vault — this is the only tool that works before NEAR_VAULT_CONTRACT is set. This server never signs it.", {
     owner: z
@@ -1300,7 +1753,12 @@ server.tool("vault_plan_add_node", "Build an UNSIGNED payload to create a budget
     limits: limitShape,
     cooldownSec: z.number().int().min(0).default(0),
     recipients: z.array(z.string()).nullable().default(null),
-}, async ({ parent, label, limits, cooldownSec, recipients }) => renderPlan(planAddNode(requireVault(), parent, label, limits, cooldownSec, recipients)));
+}, async ({ parent, label, limits, cooldownSec, recipients }) => {
+    // The PARENT's name, so the summary reads "under news" not "under node 1".
+    // Only looked up when there IS a parent.
+    const parentName = parent === null ? null : (await resolveNode(parent)).label;
+    return renderPlan(planAddNode(requireVault(), parent, label, limits, cooldownSec, recipients, parentName));
+});
 /**
  * Refuse to build a signable payload for a node that does not exist.
  *
@@ -1322,19 +1780,38 @@ server.tool("vault_plan_add_node", "Build an UNSIGNED payload to create a budget
  * them just prompts another guess.
  */
 async function assertNode(nodeId) {
+    return (await resolveNode(nodeId)).missing;
+}
+/**
+ * One tree read, answering BOTH questions a plan handler has: does this node
+ * exist, and what do humans call it?
+ *
+ * THE LABEL WAS ALREADY BEING FETCHED AND THROWN AWAY. `assertNode` read
+ * `label` purely to list it in a "no such node" message, so every plan summary
+ * said "node 1" while the word "news" sat in the same response. Returning it
+ * costs nothing and is what lets `budgetName` do its job.
+ *
+ * A FAILED READ RETURNS NO LABEL AND NO COMPLAINT. The chain being briefly
+ * unreachable is not evidence the node is missing — refusing here would turn a
+ * blip into "your node does not exist" — and it is not evidence the node is
+ * unnamed either, so the summary falls back to "this budget" rather than
+ * inventing one.
+ */
+async function resolveNode(nodeId) {
     const tree = (await viewFunction(cfg.rpcUrl, requireVault(), "get_tree", {}).catch(() => null));
-    // A failed READ must not block a plan: the chain being briefly unreachable
-    // is not evidence the node is missing, and refusing here would turn a blip
-    // into "your node does not exist".
     if (!Array.isArray(tree))
-        return null;
-    if (tree.some((n) => n.id === nodeId))
-        return null;
+        return { missing: null, label: null };
+    const hit = tree.find((n) => n.id === nodeId);
+    if (hit)
+        return { missing: null, label: hit.label ?? null };
     // RETURNS THE FACTS, NOT A SENTENCE. The first version returned prose and
     // the read path tried to reuse it by regex-stripping the signing clause,
     // which left "no node 999, Nodes: ...". Composing at the call site costs two
     // lines and cannot produce a mangled sentence.
-    return { known: tree.map((n) => `${n.id}${n.label ? ` (${n.label})` : ""}`).join(", ") };
+    return {
+        missing: { known: tree.map((n) => `${n.id}${n.label ? ` (${n.label})` : ""}`).join(", ") },
+        label: null,
+    };
 }
 /** For a PLAN: the cost of getting this wrong is a wasted signature. */
 const noNodeForPlan = (nodeId, known) => `This vault has no node ${nodeId}, so that payload would be refused by the ` +
@@ -1342,33 +1819,33 @@ const noNodeForPlan = (nodeId, known) => `This vault has no node ${nodeId}, so t
 /** For a READ: nothing is at stake, so just say what exists. */
 const noNodeForRead = (nodeId, known) => `This vault has no node ${nodeId}. Nodes: ${known}.`;
 server.tool("vault_plan_set_caps", "Build an UNSIGNED payload to change a node's daily and per-payment caps. Not signed by this server.", { nodeId: z.number().int().min(0), limits: limitShape }, async ({ nodeId, limits }) => {
-    const bad = await assertNode(nodeId);
-    return bad
-        ? text(noNodeForPlan(nodeId, bad.known))
-        : renderPlan(planSetNodeCaps(requireVault(), nodeId, limits));
+    const n = await resolveNode(nodeId);
+    return n.missing
+        ? text(noNodeForPlan(nodeId, n.missing.known))
+        : renderPlan(planSetNodeCaps(requireVault(), nodeId, limits, n.label));
 });
 server.tool("vault_plan_bind_agent", "Build an UNSIGNED payload binding a signing key to a node, so that key may spend from it. Generate the keypair yourself and pass only the public half. Many keys may share one node. Not signed by this server.", {
     nodeId: z.number().int().min(0),
     publicKey: z.string().describe("ed25519:..."),
-}, async ({ nodeId, publicKey }) => renderPlan(planBindVirtualAgent(requireVault(), nodeId, publicKey)));
+}, async ({ nodeId, publicKey }) => renderPlan(planBindVirtualAgent(requireVault(), nodeId, publicKey, (await resolveNode(nodeId)).label)));
 server.tool("vault_plan_unbind_agent", "Build an UNSIGNED payload revoking a signing key's authority to spend. Does NOT return any gas left in that key's NEP-611 gas key — withdraw from the gas key separately. Not signed by this server.", { publicKey: z.string().describe("ed25519:...") }, async ({ publicKey }) => renderPlan(planUnbindVirtualAgent(requireVault(), publicKey)));
 server.tool("vault_plan_freeze", "Build an UNSIGNED payload to freeze or unfreeze a node. Freezing blocks the node AND its whole subtree. Not signed by this server.", { nodeId: z.number().int().min(0), frozen: z.boolean() }, async ({ nodeId, frozen }) => {
-    const bad = await assertNode(nodeId);
-    return bad
-        ? text(noNodeForPlan(nodeId, bad.known))
-        : renderPlan(planFreezeNode(requireVault(), nodeId, frozen));
+    const n = await resolveNode(nodeId);
+    return n.missing
+        ? text(noNodeForPlan(nodeId, n.missing.known))
+        : renderPlan(planFreezeNode(requireVault(), nodeId, frozen, n.label));
 });
 server.tool("vault_plan_set_recipients", "Build an UNSIGNED payload to set a node's payee allowlist. This REPLACES the inherited list rather than adding to it; pass null to inherit. Not signed by this server.", { nodeId: z.number().int().min(0), recipients: z.array(z.string()).nullable() }, async ({ nodeId, recipients }) => (async () => {
-    const bad = await assertNode(nodeId);
-    return bad
-        ? text(noNodeForPlan(nodeId, bad.known))
-        : renderPlan(planSetRecipients(requireVault(), nodeId, recipients));
+    const n = await resolveNode(nodeId);
+    return n.missing
+        ? text(noNodeForPlan(nodeId, n.missing.known))
+        : renderPlan(planSetRecipients(requireVault(), nodeId, recipients, n.label));
 })());
 server.tool("vault_plan_set_cooldown", "Build an UNSIGNED payload to set the minimum seconds between a node's payments. Not signed by this server.", { nodeId: z.number().int().min(0), cooldownSec: z.number().int().min(0) }, async ({ nodeId, cooldownSec }) => {
-    const bad = await assertNode(nodeId);
-    return bad
-        ? text(noNodeForPlan(nodeId, bad.known))
-        : renderPlan(planSetCooldown(requireVault(), nodeId, cooldownSec));
+    const n = await resolveNode(nodeId);
+    return n.missing
+        ? text(noNodeForPlan(nodeId, n.missing.known))
+        : renderPlan(planSetCooldown(requireVault(), nodeId, cooldownSec, n.label));
 });
 server.tool("vault_pending_approval", "Look up a payment that is HELD awaiting the owner's approval. Returns null if there is no ticket for that id — already approved, already rejected, or never held.", { requestId: z.string().min(1) }, async ({ requestId }) => json((await viewFunction(cfg.rpcUrl, requireVault(), "get_pending_approval", {
     request_id: requestId,
@@ -1381,7 +1858,7 @@ server.tool("vault_plan_set_approval_threshold", 'Build an UNSIGNED payload requ
     // planSetApprovalThreshold in payloads.ts for the measurement.
     amount: z.string().min(1).nullable().describe('human units, e.g. "0.25" — NOT base units'),
     decimals: z.number().int().min(0).max(38).default(6),
-}, async ({ nodeId, amount, decimals }) => renderPlan(planSetApprovalThreshold(requireVault(), nodeId, amount, decimals)));
+}, async ({ nodeId, amount, decimals }) => renderPlan(planSetApprovalThreshold(requireVault(), nodeId, amount, decimals, (await resolveNode(nodeId)).label)));
 server.tool("vault_plan_approve_payment", "Build an UNSIGNED payload to APPROVE a held payment, which sends it. Every limit is re-checked at approval, so it can still be refused. Not signed by this server.", { requestId: z.string().min(1) }, async ({ requestId }) => renderPlan(planApprovePayment(requireVault(), requestId)));
 server.tool("vault_plan_reject_payment", "Build an UNSIGNED payload to REJECT a held payment. Nothing moves and the ticket is discarded. Not signed by this server.", { requestId: z.string().min(1) }, async ({ requestId }) => renderPlan(planRejectPayment(requireVault(), requestId)));
 /**