@floatonnear/mcp 0.10.1 → 0.10.3

package/SKILL.md

@@ -30,8 +30,101 @@ the agent itself can change. Float gives it a **function-call key restricted to
 one method on one contract**, and puts the limits in a contract the key cannot
 reach.
 
-Read the next section before doing anything. It is the part that decides which
-of your requests can succeed.
+**Read the two sections below before doing anything.** The first decides how you
+speak to the person you are helping; the second decides which of your requests
+can succeed at all.
+
+## How you talk to the human (non-negotiable)
+
+**You are the product voice. The human is not debugging Float.** They asked for
+something to be paid, or set up, or limited. Everything below exists because
+the natural failure mode of a coding agent is to narrate the machine — rails,
+gas keys, reason codes, env vars — to someone who wanted one sentence.
+
+**Always:**
+
+- **2–4 short sentences** for a normal outcome. Not a report.
+- **Lead with the outcome**: paid / blocked / needs your approval / needs setup.
+- **Say whether money moved.** Yes or no, explicitly. It is the one fact a
+  person cannot infer and must never have to guess.
+- **One clear next step** when something is blocked — not a menu.
+- Everyday words: limit, budget, payment, wallet, *approve in your wallet*.
+
+**Never — unless they explicitly ask for technical detail, or are plainly a
+developer debugging:**
+
+- reason codes (`PARENT_PER_TX_LIMIT`, `COOLDOWN`, …)
+- tool names (`vault_pay`, `vault_add_role`, `vault_plan_set_caps`)
+- env vars, key files, keyrings, RPC urls, gas keys, nonces, wasm, yoctoNEAR,
+  base units, node ids
+- a setup essay in the middle of a task
+- several options when one sensible default exists
+
+### Use the tool's own words
+
+Tools return the user-facing sentence already built, with the real numbers in
+it:
+
+```json
+{
+  "say": "Sent 0.25 USDC to test015.near. Money moved.",
+  "next_step": null,
+  "money_moved": true,
+  "technical": { "status": "SETTLED", "reason_code": null }
+}
+```
+
+**Relay `say`. Add `next_step` if it is not null. Stop.** Do not re-derive a
+more technical story out of `technical` — those fields are for you, and for the
+moment someone asks *why*.
+
+`say` is built where the numbers live, which is why it can name the cap that
+bound and what is left today. A sentence you compose from `status` and
+`reason_code` alone cannot, because the payment response never carried them.
+
+### Templates
+
+**Paid:**
+
+> Sent **0.25 USDC** to test015.near. Money moved. About **24.75 USDC** left in
+> today's budget.
+
+**Blocked, over a limit:**
+
+> That payment was **too big** — the most this budget allows per payment is
+> **10 USDC**, and this asked for 15. **Nothing was sent.** Try 10 USDC or
+> less, or raise the limit (I'll give you something to approve in your wallet).
+
+**Needs a human signature:**
+
+> I can't change limits myself — only you can. Here's the change to **approve
+> in your wallet**. Tell me once you have and I'll confirm it's live.
+
+**No vault yet:**
+
+> You don't have a vault yet. Setting one up is **one approval in your wallet**
+> and about **3.7 NEAR** — almost all of it a refundable deposit your vault
+> holds, not a fee. Want me to start?
+
+**Not enough money:**
+
+> The vault doesn't have enough USDC for that. **Nothing was sent.** Add USDC to
+> the vault and ask me again.
+
+### Worked examples, before and after
+
+| situation | ❌ what not to say | ✅ what to say |
+| --- | --- | --- |
+| settled | `status: SETTLED, node_id: 1` | Sent 0.25 USDC to test015.near. Money moved. 24.75 USDC left today. |
+| over cap | "BLOCKED with reason_code PARENT_PER_TX_LIMIT" | That's too big for one payment — the limit is 10 USDC and this asked for 15. Nothing was sent. |
+| policy change | "Returns an unsigned payload; the server does not sign. Run `near contract call-function`…" | I can't change the limit myself — approve this in your wallet and it's done. |
+| new agent | "Generated an ed25519 keypair, wrote it to the keyring; the 0.12 NEAR deposit funds a NEP-611 gas key" | I'll set up a news budget: 1 USDC a day, 0.10 max per payment. Approve once in your wallet and I can pay within those limits. |
+| no vault | "`NEAR_VAULT_CONTRACT` is not set" | You don't have a vault yet — want me to set one up? |
+
+A person who asked to pay a vendor and got `PARENT_PER_TX_LIMIT` has been told
+nothing they can act on. The codes are precise, and that precision is a real
+asset for debugging and for explaining the design. It is just never the first
+thing a person wants.
 
 ## Setup — do this first if you arrived here cold
 
@@ -151,11 +244,49 @@ key on the machine, which is the thing above.
   Your key's `method_names` is `["request_payment"]` and nothing else.
 - attach NEAR to anything. A NEAR function-call key cannot carry a deposit.
 - **fund the vault.** That needs the owner's tokens and the owner's key. If the
-  vault is empty, say so and ask the human — do not try to fix it yourself.
+  vault is empty, say so and ask the human — do not try to fix it yourself, and
+  send them to their WALLET, never to a CLI. See below.
 
 If a request needs one of those, produce a plan with `vault_plan_*` and hand it
 to the human. Do not attempt it and report the error.
 
+### Funding a vault — the wallet, always, never the CLI
+
+Someone has to put tokens in. **Tell them to send from their own wallet**, name
+the three fields, and stop:
+
+> Open your wallet as `<owner>` and send `<amount>` `<TOKEN>` to `<vault>`.
+> Check the token's CONTRACT ID, not just the ticker — `<contract>`.
+
+**Do NOT hand over an `ft_transfer` command, and do not offer to run one.**
+Measured 2026-11-13: asked to fund a vault, an agent found a full-access key in
+`~/.near-credentials` and offered `near call … ft_transfer` as a co-equal option
+beside the wallet. The user had to correct it. A token send is the one operation
+every wallet already does well — a button, with the balance, the ticker and the
+destination on screen before anything is signed. Replacing that with base-unit
+arithmetic (`"amount":"1000000"`), a `--depositYocto 1` the user cannot
+sanity-check, and a key read off disk is worse precisely when they are deciding
+whether to trust this thing with money.
+
+It also contradicts the rest of this file. Creation already refuses the CLI for
+anyone being onboarded — *"never offer to run the CLI on someone else's
+behalf"* — and funding is the same situation with the same answer. The wizard's
+`--fund` flag belongs to an operator on their own machine with their own key; it
+is not a funding path to offer a user.
+
+Two things to say in the same message, because both fail SILENTLY:
+
+- **the token contract, not the ticker.** Caps are keyed per token. NEAR has a
+  native USDC and an older bridged `USDC.e` — send the wrong one and it arrives,
+  shows as a balance, and the agent still has zero budget for it. The refusal
+  reads as a broken vault.
+- **the payee allowlist.** Read it with `vault_tree` first. If it still holds
+  only the owner, the agent can pay nobody but the owner, and funding past a
+  test amount buys nothing yet.
+
+Then verify instead of taking their word for it: read the vault's
+`ft_balance_of` and tell them what actually landed.
+
 ## Daily use — the MCP tools
 
 If `float` is configured in your MCP client, you have these. Read before you
@@ -269,10 +400,13 @@ A refusal comes back as a **value**, not an error. `status: "BLOCKED"` with a
 
 ### Never show a reason code to the user
 
-`vault_pay` already returns a plain-English `say`, a `next_step`, and a
-`money_moved` flag. **Relay `say`, add `next_step` if there is one, and stop.**
-The `reason_code` lives under `technical`; quote it only if the user asks why,
-asks for detail, or is plainly a developer.
+This is governed by **How you talk to the human** near the top of this file —
+one source of truth, so the two cannot drift apart. The short form:
+
+**`vault_pay` returns `say`, `next_step` and `money_moved`. Relay `say`, add
+`next_step` if it is not null, and stop.** The `reason_code` lives under
+`technical`; quote it only if the user asks why, asks for detail, or is plainly
+a developer.
 
 > Say: *"That's too big for one payment — the most per payment is 10 USDC, and
 > this asked for 15. Nothing was sent. Send 10 USDC or less, or ask the vault
@@ -280,13 +414,9 @@ asks for detail, or is plainly a developer.
 >
 > Not: *"The payment was BLOCKED with reason_code PARENT_PER_TX_LIMIT."*
 
-The same applies when it works: *"Sent 0.25 USDC to alice.near. There's 24.75
-USDC left to spend today."* — not `status: SETTLED`.
-
-Someone who asked to pay a vendor and got `PARENT_PER_TX_LIMIT` has been told
-nothing they can act on. The codes are precise and that precision is a real
-asset for debugging and for explaining the design — it is just not what a
-person wants first.
+**A refusal is still an answer, not a failure.** Report it as the budget doing
+its job. And never imply money moved when `money_moved` is false — a blocked
+payment moved nothing, which is the whole point.
 
 ### The codes themselves
 

package/dist/agent-key.d.ts

@@ -50,6 +50,22 @@ export interface GeneratedAgentKey {
 export declare function generateAgentKey(opts: {
     vault: string;
     dir?: string;
+    /**
+     * The exact keyring file to write, overriding `dir` and the hardcoded
+     * `agent-keys.json` filename.
+     *
+     * WHY IT HAS TO EXIST. The caller configures a keyring by full PATH
+     * (`NEAR_VAULT_AGENT_KEYS`), and this function used to accept only a
+     * directory and append a fixed filename. So pinning the keyring to, say,
+     * `~/keys/fleet.json` meant the server READ `fleet.json` and WROTE
+     * `~/keys/agent-keys.json` — a brand new agent, filed where nothing would
+     * ever look for it, reported as success. Silent, and exactly the "written
+     * somewhere you are not reading" failure this module is supposed to prevent.
+     *
+     * Caught by the smoke test that pins a non-default filename, not by a unit
+     * test: every unit test here passes a directory.
+     */
+    keyringPath?: string;
     /**
      * The node this agent spends from.
      *
@@ -85,3 +101,37 @@ export declare function agentKeyPaths(dir?: string): {
     envPath: string;
     dir: string;
 };
+/**
+ * Take a role name off a keyring entry that is PROVEN not bound on chain,
+ * without destroying its secret.
+ *
+ * WHY THIS IS NEEDED. `generateAgentKey` appends and never replaces, for the
+ * reason above: overwriting could destroy the only copy of a credential for an
+ * agent that is already bound and funded. But `selectRole` resolves a role with
+ * `entries.find(...)` — FIRST match wins. So an orphaned entry (a key written
+ * by a `vault_add_role` that then failed to land on chain) would permanently
+ * SHADOW the replacement: every future payment under that role would select a
+ * key the contract answers NOT_VIRTUAL_AGENT for, and the working key beside it
+ * would never be reached.
+ *
+ * So the orphan's role is RENAMED rather than deleted. The secret stays on
+ * disk, the entry stays in the file, and the name resolves to exactly one
+ * credential again. Deleting would be tidier and is not worth the risk: the
+ * caller's proof of deadness is a chain read, and a chain read can be wrong
+ * about a vault that is paused, migrating, or being served by a lagging RPC.
+ * A renamed entry survives that mistake; a deleted one does not.
+ *
+ * Identified BY PUBLIC KEY, never by role alone — the whole point is that two
+ * entries can share a role at this moment, and renaming the wrong one would
+ * retire the live agent.
+ *
+ * Returns the new role name, or null if no entry matched (already retired, or
+ * a keyring that moved under us) — which is not an error.
+ */
+export declare function retireRole(opts: {
+    keyringPath: string;
+    vault: string;
+    publicKey: string;
+}): {
+    retiredTo: string;
+} | null;

package/dist/agent-key.js

@@ -58,11 +58,13 @@ export const AGENT_NODE_ID = 1;
  * `NEAR_VAULT_AGENT_ID` is set to a vault id in `.mcp.json`.
  */
 export function generateAgentKey(opts) {
-    const dir = opts.dir ?? ".float";
     // `undefined` -> root (the creation-time agent). `null` -> unknown, and the
     // field is omitted rather than guessed.
     const nodeId = opts.nodeId === null ? undefined : (opts.nodeId ?? AGENT_NODE_ID);
-    const keyringPath = join(dir, "agent-keys.json");
+    // An explicit path wins and decides the directory; otherwise the old
+    // dir-plus-fixed-filename behaviour, unchanged.
+    const keyringPath = opts.keyringPath ?? join(opts.dir ?? ".float", "agent-keys.json");
+    const dir = dirname(keyringPath);
     const envPath = join(dir, "agent.env");
     const kp = KeyPair.fromRandom("ed25519");
     const publicKey = kp.getPublicKey().toString();
@@ -133,3 +135,67 @@ export function generateAgentKey(opts) {
 export function agentKeyPaths(dir = ".float") {
     return { keyringPath: join(dir, "agent-keys.json"), envPath: join(dir, "agent.env"), dir: dirname(join(dir, "x")) };
 }
+/**
+ * Take a role name off a keyring entry that is PROVEN not bound on chain,
+ * without destroying its secret.
+ *
+ * WHY THIS IS NEEDED. `generateAgentKey` appends and never replaces, for the
+ * reason above: overwriting could destroy the only copy of a credential for an
+ * agent that is already bound and funded. But `selectRole` resolves a role with
+ * `entries.find(...)` — FIRST match wins. So an orphaned entry (a key written
+ * by a `vault_add_role` that then failed to land on chain) would permanently
+ * SHADOW the replacement: every future payment under that role would select a
+ * key the contract answers NOT_VIRTUAL_AGENT for, and the working key beside it
+ * would never be reached.
+ *
+ * So the orphan's role is RENAMED rather than deleted. The secret stays on
+ * disk, the entry stays in the file, and the name resolves to exactly one
+ * credential again. Deleting would be tidier and is not worth the risk: the
+ * caller's proof of deadness is a chain read, and a chain read can be wrong
+ * about a vault that is paused, migrating, or being served by a lagging RPC.
+ * A renamed entry survives that mistake; a deleted one does not.
+ *
+ * Identified BY PUBLIC KEY, never by role alone — the whole point is that two
+ * entries can share a role at this moment, and renaming the wrong one would
+ * retire the live agent.
+ *
+ * Returns the new role name, or null if no entry matched (already retired, or
+ * a keyring that moved under us) — which is not an error.
+ */
+export function retireRole(opts) {
+    if (!existsSync(opts.keyringPath))
+        return null;
+    let entries;
+    try {
+        const parsed = JSON.parse(readFileSync(opts.keyringPath, "utf8"));
+        if (!Array.isArray(parsed))
+            return null;
+        entries = parsed;
+    }
+    catch {
+        // Unreadable is not this function's problem to fix; `generateAgentKey`
+        // already backs such a file aside before writing.
+        return null;
+    }
+    let retiredTo;
+    for (const e of entries) {
+        if (!e || typeof e !== "object")
+            continue;
+        if (e.agentId !== opts.vault)
+            continue;
+        if (e.publicKey !== opts.publicKey)
+            continue;
+        if (typeof e.role !== "string")
+            continue;
+        // A short slice of the public key keeps two retirements of the same role
+        // from colliding, and keeps the name traceable back to the exact entry.
+        retiredTo = `${e.role}-retired-${opts.publicKey.slice(8, 16)}`;
+        e.role = retiredTo;
+        // The node id, if any, was never real for an unbound key.
+        delete e.nodeId;
+    }
+    if (!retiredTo)
+        return null;
+    writeFileSync(opts.keyringPath, `${JSON.stringify(entries, null, 2)}${String.fromCharCode(10)}`);
+    return { retiredTo };
+}

package/dist/create.d.ts

@@ -62,6 +62,16 @@ export declare const STORAGE_COST_PER_BYTE: bigint;
  * copy that drifts.
  */
 export declare const PAGE_HEADROOM_YOCTO: bigint;
+/**
+ * NEP-145 registration for ONE token, mirroring the factory's
+ * `TOKEN_REGISTRATION` and the vault's `DEPOSIT_ADDRESS_STORAGE`.
+ *
+ * The factory registers a new vault on every token named in `root_limits`, so
+ * a plain `ft_transfer` into it succeeds — before that it failed with "the
+ * account is not registered", which broke funding for every browser-created
+ * vault. Pinned against the contract by `create.pins.test.ts`.
+ */
+export declare const TOKEN_REGISTRATION_YOCTO: bigint;
 /**
  * Funding for an agent's gas key, when one is bound at creation.
  *

package/dist/create.js

@@ -62,6 +62,16 @@ export const STORAGE_COST_PER_BYTE = 10n ** 19n;
  * copy that drifts.
  */
 export const PAGE_HEADROOM_YOCTO = 36n * 10n ** 22n;
+/**
+ * NEP-145 registration for ONE token, mirroring the factory's
+ * `TOKEN_REGISTRATION` and the vault's `DEPOSIT_ADDRESS_STORAGE`.
+ *
+ * The factory registers a new vault on every token named in `root_limits`, so
+ * a plain `ft_transfer` into it succeeds — before that it failed with "the
+ * account is not registered", which broke funding for every browser-created
+ * vault. Pinned against the contract by `create.pins.test.ts`.
+ */
+export const TOKEN_REGISTRATION_YOCTO = 125n * 10n ** 19n;
 /**
  * Funding for an agent's gas key, when one is bound at creation.
  *
@@ -258,8 +268,20 @@ export function buildCreatePlan(i) {
     // Both floors move by the gas-key funding when an agent is bound: the page
     // attaches it, and the factory requires it.
     const agentFunding = i.agentPk ? AGENT_GAS_KEY_FUNDING_YOCTO : 0n;
+    /**
+     * The factory also registers the new vault on each token in `root_limits`,
+     * so its floor covers that too — otherwise it would fund those receipts from
+     * its OWN balance, which is the drain documented in the contract.
+     *
+     * Counted as ONE because `vault_create` builds a single-token `root_limits`.
+     * It does not change the quoted total today: the page's 0.36 headroom keeps
+     * `pageAttaches` above the floor either way, and `max` picks the page. It is
+     * included so the floor stays correct if an operator raises
+     * `required_deposit` and the floor becomes the binding term.
+     */
+    const registrations = TOKEN_REGISTRATION_YOCTO;
     const pageAttaches = stake + PAGE_HEADROOM_YOCTO + agentFunding;
-    const factoryFloor = BigInt(i.requiredDepositYocto) + stake + agentFunding;
+    const factoryFloor = BigInt(i.requiredDepositYocto) + stake + agentFunding + registrations;
     const deposit = pageAttaches > factoryFloor ? pageAttaches : factoryFloor;
     const total = deposit + GAS_RESERVATION_YOCTO;
     // If the operator raises `required_deposit` past the page's headroom, the

package/dist/explain.d.ts

@@ -57,3 +57,36 @@ export interface Explanation {
     moved: boolean;
 }
 export declare function explainOutcome(c: OutcomeContext): Explanation;
+/**
+ * The user-facing sentence for an UNSIGNED owner payload.
+ *
+ * WHY PLAN TOOLS NEEDED THIS TOO. `vault_pay` returned `say`/`next_step`/
+ * `money_moved` and the plan tools returned `{action, summary, warnings,
+ * unsigned_payload, approve_with}` — five technical keys and no sentence. So
+ * agents narrated the mechanism: "returns an unsigned payload; the server does
+ * not sign; run `near contract call-function`…". All true, and unusable by the
+ * person who asked to raise a limit.
+ *
+ * THE THREE THINGS A PERSON NEEDS HERE, in order:
+ *   1. this needs YOU — the agent cannot do it
+ *   2. what it will do, in the units they named
+ *   3. nothing has happened yet
+ *
+ * (3) matters most and is the easiest to leave out. An unsigned payload is a
+ * *proposal*; an agent that says "I've raised the limit" has lied about state
+ * the user is about to be asked to change themselves.
+ *
+ * `summary` is reused verbatim rather than rewritten. It is built where the
+ * amounts and tokens are known, in the units the caller passed, and
+ * duplicating that formatting here is how the two drift into disagreeing about
+ * a number. It does still say "node 1" — the honest fix for that is better
+ * summaries in `payloads.ts`, not a second renderer guessing at them here.
+ */
+export declare function planVoice(p: {
+    summary: string;
+    depositYocto?: string;
+    warnings?: string[];
+}): {
+    say: string;
+    next: string;
+};

package/dist/explain.js

@@ -207,3 +207,58 @@ export function explainOutcome(c) {
         }
     }
 }
+/**
+ * The user-facing sentence for an UNSIGNED owner payload.
+ *
+ * WHY PLAN TOOLS NEEDED THIS TOO. `vault_pay` returned `say`/`next_step`/
+ * `money_moved` and the plan tools returned `{action, summary, warnings,
+ * unsigned_payload, approve_with}` — five technical keys and no sentence. So
+ * agents narrated the mechanism: "returns an unsigned payload; the server does
+ * not sign; run `near contract call-function`…". All true, and unusable by the
+ * person who asked to raise a limit.
+ *
+ * THE THREE THINGS A PERSON NEEDS HERE, in order:
+ *   1. this needs YOU — the agent cannot do it
+ *   2. what it will do, in the units they named
+ *   3. nothing has happened yet
+ *
+ * (3) matters most and is the easiest to leave out. An unsigned payload is a
+ * *proposal*; an agent that says "I've raised the limit" has lied about state
+ * the user is about to be asked to change themselves.
+ *
+ * `summary` is reused verbatim rather than rewritten. It is built where the
+ * amounts and tokens are known, in the units the caller passed, and
+ * duplicating that formatting here is how the two drift into disagreeing about
+ * a number. It does still say "node 1" — the honest fix for that is better
+ * summaries in `payloads.ts`, not a second renderer guessing at them here.
+ */
+export function planVoice(p) {
+    const bits = [];
+    // (1) and (2) together, because "needs you" is meaningless without "to do
+    // what". Leading with the actor is what stops the agent claiming the credit.
+    bits.push(`This one needs you — I can't make this change myself. ${p.summary}.`);
+    /**
+     * A DEPOSIT IS STATED, ALWAYS, WHEN THERE IS ONE.
+     *
+     * 1 yoctoNEAR is the NEP-141 anti-phishing deposit — a rounding error that
+     * no person should ever be told about. Anything larger is real money leaving
+     * their wallet, and a wallet prompt showing an unexplained NEAR figure is
+     * the fastest way to make a safe action look like a scam.
+     */
+    const dep = BigInt(p.depositYocto ?? "0");
+    if (dep > 1n) {
+        const near = (Number(dep) / 1e24).toFixed(3).replace(/\.?0+$/, "");
+        bits.push(`It sends ${near} NEAR with it, which the vault keeps — not a fee.`);
+    }
+    // (3). Said last so it is the thing left ringing.
+    bits.push("Nothing has changed yet.");
+    // `warnings` is non-empty only for destructive or hard-to-undo actions, so
+    // when one exists it outranks brevity.
+    const firstWarning = (p.warnings ?? []).find((w) => typeof w === "string" && !!w.trim());
+    if (firstWarning)
+        bits.push(firstWarning);
+    return {
+        say: bits.join(" "),
+        next: "Approve it in your wallet, then tell me and I'll confirm it went through.",
+    };
+}

package/dist/keyring-path.d.ts

@@ -0,0 +1,36 @@
+export declare const KEYRING_FILENAME: string;
+export interface ResolvedKeyring {
+    /** Absolute path. Never relative — that is the whole point of this module. */
+    path: string;
+    /** Plain-English reason, safe to show a user. Names no secrets. */
+    why: string;
+    /**
+     * Other keyrings that ALSO hold a credential for this vault and are not
+     * being read. Empty in the normal case. Non-empty means a split keyring,
+     * which a user needs told rather than silently resolved.
+     */
+    alsoFound: string[];
+}
+/**
+ * How many credentials a keyring file holds for `vault`.
+ *
+ * Deliberately TOLERANT about the credential field name. `roles.ts` loads only
+ * `secret`, but `prove-refusal.mjs` reads `privateKey ?? secret ?? agentKey`,
+ * and a file written by one path must still be FOUND by this one — otherwise
+ * resolution sends the user to an empty home keyring while their real keys sit
+ * in a shape this function refused to count. Finding the file and loading an
+ * entry out of it are different jobs; `listUnloadable` reports the second.
+ *
+ * Never throws, and never returns the contents. A corrupt or unreadable file
+ * counts as zero; the caller is choosing a path, not validating a keyring.
+ */
+export declare function countFor(path: string, vault?: string): number;
+export declare function resolveKeyringPath(opts: {
+    /** The raw `NEAR_VAULT_AGENT_KEYS` value, if the operator set one. */
+    explicit?: string;
+    vault?: string;
+    /** Injectable so a test does not depend on where it was run from. */
+    cwd?: string;
+    home?: string;
+    count?: (path: string, vault?: string) => number;
+}): ResolvedKeyring;

package/dist/keyring-path.js

@@ -0,0 +1,117 @@
+/**
+ * WHERE THE FLEET KEYRING LIVES — and why it must not be a relative path.
+ *
+ * THE BUG THIS EXISTS TO KILL. The default was the bare string
+ * `.float/agent-keys.json`, which Node resolves against `process.cwd()`. An MCP
+ * server's CWD is wherever the CLIENT was launched, which the user does not
+ * choose and cannot see. So one single server entry in `~/.claude.json` became
+ * a DIFFERENT keyring per directory:
+ *
+ *   launched from  New project\   ->  New project\.float\agent-keys.json
+ *   launched from  near-vault\    ->  near-vault\.float\agent-keys.json
+ *
+ * Measured 2026-11-13 on this machine: `NEAR_VAULT_AGENT_KEYS` is UNSET for the
+ * `float` server, so a `travel` agent key written from one directory was
+ * invisible from the other. The tool reported "no agent with role 'travel'"
+ * while the key sat on disk a few folders away. Nothing in the output could
+ * distinguish "never created" from "created somewhere you are not looking",
+ * which is the same shape as the keyring-reader disagreement `roles.ts` already
+ * has a comment about.
+ *
+ * THE RULE. Resolution answers one question: *which file can sign for THIS
+ * vault?* Not "which directory am I in".
+ *
+ *   1. `NEAR_VAULT_AGENT_KEYS` set  -> that, made absolute. Explicit wins; an
+ *      operator who pinned a path gets the path they pinned.
+ *   2. Otherwise, of the CWD keyring and the HOME keyring, the one that already
+ *      holds a credential for this vault. This is the back-compat case: anyone
+ *      whose keys are in a project-local `.float/` keeps working untouched.
+ *   3. Otherwise HOME — `~/.float/agent-keys.json`. New keys land somewhere
+ *      stable, so the NEXT session finds them whatever directory it starts in.
+ *
+ * Rule 3 is the actual fix. Rules 1 and 2 are there so turning it on cannot
+ * strand a key that already exists.
+ *
+ * WHEN BOTH HOLD KEYS it is a split keyring, and picking silently would hide
+ * one agent's roles behind another's. One is chosen so the tool still works,
+ * and the other is RETURNED in `alsoFound` so a caller can say so out loud.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+export const KEYRING_FILENAME = join(".float", "agent-keys.json");
+/**
+ * How many credentials a keyring file holds for `vault`.
+ *
+ * Deliberately TOLERANT about the credential field name. `roles.ts` loads only
+ * `secret`, but `prove-refusal.mjs` reads `privateKey ?? secret ?? agentKey`,
+ * and a file written by one path must still be FOUND by this one — otherwise
+ * resolution sends the user to an empty home keyring while their real keys sit
+ * in a shape this function refused to count. Finding the file and loading an
+ * entry out of it are different jobs; `listUnloadable` reports the second.
+ *
+ * Never throws, and never returns the contents. A corrupt or unreadable file
+ * counts as zero; the caller is choosing a path, not validating a keyring.
+ */
+export function countFor(path, vault) {
+    if (!existsSync(path))
+        return 0;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return 0;
+    }
+    if (!Array.isArray(parsed))
+        return 0;
+    return parsed.filter((e) => {
+        if (!e || typeof e !== "object")
+            return false;
+        const id = e.agentId ?? e.vault;
+        if (vault && id !== vault)
+            return false;
+        return ["secret", "privateKey", "agentKey"].some((k) => typeof e[k] === "string");
+    }).length;
+}
+export function resolveKeyringPath(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    const count = opts.count ?? countFor;
+    if (opts.explicit) {
+        // Resolved even when already absolute, so the returned path is normalised
+        // and a relative override still cannot vary with CWD mid-session.
+        const path = isAbsolute(opts.explicit) ? opts.explicit : resolve(cwd, opts.explicit);
+        return { path, why: "NEAR_VAULT_AGENT_KEYS is set", alsoFound: [] };
+    }
+    const cwdRing = resolve(cwd, KEYRING_FILENAME);
+    const homeRing = join(home, KEYRING_FILENAME);
+    // Same directory: nothing to choose between, and no split to report.
+    if (cwdRing === homeRing) {
+        return { path: homeRing, why: "the default keyring in your home folder", alsoFound: [] };
+    }
+    const inCwd = count(cwdRing, opts.vault);
+    const inHome = count(homeRing, opts.vault);
+    if (inCwd > 0 && inHome === 0) {
+        return {
+            path: cwdRing,
+            why: "it already holds a key for this vault",
+            alsoFound: [],
+        };
+    }
+    if (inHome > 0 && inCwd > 0) {
+        return {
+            path: homeRing,
+            why: "it holds a key for this vault",
+            // The one NOT being read. Surfaced so "my agent vanished" is answerable.
+            alsoFound: [cwdRing],
+        };
+    }
+    return {
+        path: homeRing,
+        why: inHome > 0
+            ? "it already holds a key for this vault"
+            : "the default keyring in your home folder, so the next session finds it from any directory",
+        alsoFound: [],
+    };
+}