@finchagentic/mcp 4.0.0 → 4.2.0

package/dist/tools/vault.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VAULT_TOOLS = void 0;
+exports.buildVaultList = buildVaultList;
+exports.buildVaultSearch = buildVaultSearch;
 exports.handleVaultTool = handleVaultTool;
 const zod_1 = require("zod");
 const convex_js_1 = require("../convex.js");
@@ -11,7 +13,7 @@ const VAULT_TYPES = ["research", "execution", "workflow", "prompt", "file", "mem
 exports.VAULT_TOOLS = [
     {
         name: "vault_save",
-        description: "Save or update a versioned artifact in Noel-Vault. Same key = update (git-style: prior version snapshotted, patched to v+1). " +
+        description: "Save or update a versioned artifact in Finch Vault. Same key = update (git-style: prior version snapshotted, patched to v+1). " +
             "Types: research | execution | workflow | prompt | file | memory. " +
             "Entries up to 10MB - content over 600KB auto-offloads to blob storage. " +
             "For quick unstructured notes, use memory_add instead.",
@@ -33,7 +35,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_read",
-        description: "Read a Noel-Vault entry by its key. Returns full content, version, tags, and any linked entries.",
+        description: "Read a Finch Vault entry by its key. Returns full content, version, tags, and any linked entries.",
         inputSchema: {
             type: "object",
             properties: {
@@ -44,7 +46,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_list",
-        description: "List Noel-Vault entries. Filter by type, agent, or pinned status. Returns previews, not full content.",
+        description: "List Finch Vault entries. Filter by type, agent, or pinned status. Returns previews, not full content.",
         inputSchema: {
             type: "object",
             properties: {
@@ -58,14 +60,14 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_search",
-        description: "Search Noel-Vault using semantic AI search (powered by Supermemory) when available, " +
-            "with automatic fallback to full-text search. Semantic search understands meaning - " +
-            "'low risk DeFi yield' matches 'conservative staking strategies' without exact keywords. " +
+        description: "Search Finch Vault using full-text (keyword) search over titles, content, and tags. " +
+            "This is lexical matching, not embeddings - exact and near words in your query rank " +
+            "highest, so short specific phrases work better than long abstract descriptions. " +
             "Optionally filter by type. Returns ranked results with previews.",
         inputSchema: {
             type: "object",
             properties: {
-                query: { type: "string", description: "Search query - natural language works best with semantic mode" },
+                query: { type: "string", description: "Search query - specific keywords work better than abstract phrasing (this is full-text search, not semantic)" },
                 type: { type: "string", enum: [...VAULT_TYPES], description: "Narrow search to a specific type" },
                 limit: { type: "number", description: "Max results (default 20)" },
             },
@@ -74,7 +76,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_history",
-        description: "Get the full version history of a Noel-Vault entry - like git log. " +
+        description: "Get the full version history of a Finch Vault entry - like git log. " +
             "Shows each version with its commit message, author agent, size, and timestamp.",
         inputSchema: {
             type: "object",
@@ -86,7 +88,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_diff",
-        description: "Compare two versions of a Noel-Vault entry - like git diff. " +
+        description: "Compare two versions of a Finch Vault entry - like git diff. " +
             "Shows lines added (+) and removed (-) between fromVersion and toVersion.",
         inputSchema: {
             type: "object",
@@ -100,7 +102,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_export",
-        description: "Export your entire Noel-Vault or a specific type as a structured bundle. " +
+        description: "Export your entire Finch Vault or a specific type as a structured bundle. " +
             "Useful for archiving, syncing to GitHub, or passing context to another agent.",
         inputSchema: {
             type: "object",
@@ -139,7 +141,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_pin",
-        description: "Pin or unpin a Noel-Vault entry. Pinned entries always appear first in vault_list and are " +
+        description: "Pin or unpin a Finch Vault entry. Pinned entries always appear first in vault_list and are " +
             "prioritized in memory_context and search results. Use for your most important research, key prompts, or canonical references.",
         inputSchema: {
             type: "object",
@@ -152,7 +154,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_unpublish",
-        description: "Make a previously shared Noel-Vault entry private again, removing it from the public community " +
+        description: "Make a previously shared Finch Vault entry private again, removing it from the public community " +
             "listing. Use this to reverse vault publishing or packet_share. Note that anyone who already " +
             "copied the content while it was public still has it — unpublishing stops future discovery, " +
             "it does not retract what was taken.",
@@ -166,7 +168,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_delete",
-        description: "PERMANENT. Delete a Noel-Vault entry and ALL of its version history — this cannot be undone. " +
+        description: "PERMANENT. Delete a Finch Vault entry and ALL of its version history — this cannot be undone. " +
             "Requires confirm: true. Use vault_list to browse first, and show the user the exact entry " +
             "(key + title) you are about to destroy before confirming.",
         inputSchema: {
@@ -180,7 +182,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_tag",
-        description: "Add or replace tags on an existing Noel-Vault entry without modifying its content. " +
+        description: "Add or replace tags on an existing Finch Vault entry without modifying its content. " +
             "Useful for organizing entries retroactively. Set replace=true to overwrite all existing tags.",
         inputSchema: {
             type: "object",
@@ -194,7 +196,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_link",
-        description: "Create a semantic relationship between two Noel-Vault entries - building a knowledge graph. " +
+        description: "Create a semantic relationship between two Finch Vault entries - building a knowledge graph. " +
             "Relations: references | derived_from | supersedes | related | continues. " +
             "Example: link a synthesis entry as 'derived_from' several research entries, or mark a newer analysis as 'supersedes' an older one. " +
             "Duplicate links are updated in-place.",
@@ -214,7 +216,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_related",
-        description: "Traverse the Noel-Vault knowledge graph - get all entries linked to a given entry. " +
+        description: "Traverse the Finch Vault knowledge graph - get all entries linked to a given entry. " +
             "Returns both outbound links (entries this entry references) and inbound links (entries that reference this one). " +
             "Filter by relation type to find only derived entries, superseded versions, continuations, etc.",
         inputSchema: {
@@ -280,6 +282,35 @@ function formatBytes(n) {
 function formatDate(ts) {
     return new Date(ts).toUTCString();
 }
+// ── Structured output builders (schemas in output-schemas.ts) ───────────────
+function buildVaultList(entries, type) {
+    return {
+        type: type ?? null,
+        count: entries.length,
+        entries: entries.map((e) => ({
+            key: e.key,
+            title: e.title ?? null,
+            type: e.type ?? null,
+            version: e.version ?? null,
+            size: e.size ?? null,
+            updatedAt: e.updatedAt ?? null,
+            isPinned: !!e.isPinned,
+        })),
+    };
+}
+function buildVaultSearch(query, results) {
+    return {
+        query,
+        count: results.length,
+        results: results.map((r) => ({
+            key: r.key,
+            title: r.title ?? null,
+            type: r.type ?? null,
+            score: r.score ?? null,
+            preview: r.preview ?? null,
+        })),
+    };
+}
 // ─── Handler ─────────────────────────────────────────────────────────────────
 async function handleVaultTool(name, args) {
     // When the user has opted into a fully-local, user-owned vault
@@ -292,6 +323,20 @@ async function handleVaultTool(name, args) {
             const parsed = SaveSchema.safeParse(args);
             if (!parsed.success)
                 return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+            if (parsed.data.type === "credential") {
+                // vault_save writes plaintext to disk/DB - "credential" is only a
+                // valid FILTER value for vault_list/search/export (which correctly
+                // exclude it), never a valid type to actually SAVE through here.
+                // vault_store_credential is the only path that encrypts at rest.
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Use `vault_store_credential` to save a secret - it encrypts at rest (AES-256-GCM). " +
+                                "`vault_save` writes plaintext, so `type: \"credential\"` is refused here.",
+                        }],
+                    isError: true,
+                };
+            }
             // Auto-generate title from content if not provided
             const firstLine = parsed.data.content.split("\n")[0].replace(/^#+\s*/, "").slice(0, 80);
             const autoTitle = parsed.data.title ?? (firstLine || `${parsed.data.type} - ${new Date().toISOString().slice(0, 10)}`);
@@ -302,7 +347,7 @@ async function handleVaultTool(name, args) {
             if (data.error)
                 return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
             const { key, version, changed } = data;
-            // Mirror to semantic memory (fire-and-forget). Skip when running a local
+            // Mirror to searchable memory (fire-and-forget). Skip when running a local
             // vault WITHOUT local memory - otherwise the mirror would phone home to
             // the hosted proxy (needs auth the local-only user doesn't have, and
             // ships their data off-machine, defeating the whole point). vault_search
@@ -335,7 +380,7 @@ async function handleVaultTool(name, args) {
                 `Key: \`${key}\``,
                 `Version: v${version}`,
                 changed && version > 1 ? `Previous version auto-snapshotted.` : "",
-                mirrorToMemory ? `🧠 Synced to semantic memory` : (localVault ? `💾 Stored locally at ~/.finch/vault` : ""),
+                mirrorToMemory ? `🧠 Synced to searchable memory` : (localVault ? `💾 Stored locally at ~/.finch/vault` : ""),
                 ...linkSummary,
                 ``,
                 `Use \`vault_read\` to retrieve, \`vault_history\` to see all versions.`,
@@ -361,7 +406,7 @@ async function handleVaultTool(name, args) {
                                     `vault_read: entry \`${vaultReadKey}\` not found.`,
                                     ``,
                                     `Try searching for it:`,
-                                    `- \`vault_search query="${searchTerms}"\` — semantic search across all entries`,
+                                    `- \`vault_search query="${searchTerms}"\` — full-text search across all entries`,
                                     `- \`vault_list\` — browse all entries`,
                                     `- \`vault_search query="${vaultReadKey.split("/")[0]}"\` — search by type prefix`,
                                 ].join("\n") }], isError: true };
@@ -383,17 +428,14 @@ async function handleVaultTool(name, args) {
                 }
                 return { content: [{ type: "text", text: `vault_read error: ${data.error}` }], isError: true };
             }
-            // Large entries are offloaded to Convex File Storage. The doc holds a
-            // preview only; pull the real content from /vault/blob.
-            let fullContent = data.content ?? "";
-            if (data.contentFileId) {
-                try {
-                    fullContent = await (0, convex_js_1.callConvexRaw)(`/vault/blob?id=${encodeURIComponent(data.contentFileId)}`, "vault_read");
-                }
-                catch (err) {
-                    fullContent = (data.content ?? "") + `\n\n_(could not load full blob: ${err.message})_`;
-                }
-            }
+            // NOTE: there is no blob-storage tier on the backend (see
+            // app/convex/vault.ts MAX_CONTENT_BYTES comment) - oversized content is
+            // rejected at save time, not offloaded to file storage, so `contentFileId`
+            // never comes back on a vault entry. A `/vault/blob` fallback used to live
+            // here but the route was never registered in http.ts either, so it was
+            // dead in both directions - removed rather than fixed against a storage
+            // tier that doesn't exist. Re-add only alongside building that tier.
+            const fullContent = data.content ?? "";
             const sizeLabel = data.originalSize ? formatBytes(data.originalSize) : formatBytes(data.size);
             const backlinksBlock = Array.isArray(data.backlinks) && data.backlinks.length > 0
                 ? `\n🔙 Linked from (${data.backlinks.length}):\n${data.backlinks.map((b) => `  ← \`${b.key}\`${b.title ? ` - ${b.title}` : ""}`).join("\n")}`
@@ -433,21 +475,35 @@ async function handleVaultTool(name, args) {
             if (data.error)
                 return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
             const entries = data.entries ?? [];
-            if (!entries.length)
-                return { content: [{ type: "text", text: `No vault entries found${parsed.data.type ? ` of type '${parsed.data.type}'` : ""}.` }] };
-            const header = `📚 **Noel-Vault** (${entries.length} entries)`;
+            if (!entries.length) {
+                return {
+                    content: [{ type: "text", text: `No vault entries found${parsed.data.type ? ` of type '${parsed.data.type}'` : ""}.` }],
+                    structuredContent: buildVaultList([], parsed.data.type),
+                };
+            }
+            const header = `📚 **Finch Vault** (${entries.length} entries)`;
             const rows = entries.map((e) => `${e.isPinned ? "📌 " : ""}[\`${e.key}\`] ${e.title} - v${e.version} · ${e.type} · ${formatBytes(e.size)} · ${formatDate(e.updatedAt)}`);
-            return { content: [{ type: "text", text: [header, "", ...rows].join("\n") }] };
+            return {
+                content: [{ type: "text", text: [header, "", ...rows].join("\n") }],
+                structuredContent: buildVaultList(entries, parsed.data.type),
+            };
         }
         case "vault_search": {
             const parsed = SearchSchema.safeParse(args);
             if (!parsed.success)
                 return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
-            // Try semantic search first (proxied through Convex). Large vault
+            // Full-text search, proxied through Convex (searchSupermemory is a
+            // legacy name - it calls Finch's own /memory/search endpoint, not a
+            // third-party semantic service; there is no embedding step here). Large vault
             // entries are indexed as multiple chunks tagged with isVaultChunk +
             // vaultKey - group chunks back to their parent entry so the result
             // list shows one row per entry, not one row per chunk.
-            {
+            //
+            // Skipped entirely when vaultBackend is local - a local vault's whole
+            // point is "no network," so the query string must never leave the
+            // machine, not even to check for results before falling back to the
+            // (always-local) full-text branch below.
+            if (!localVault) {
                 const limit = parsed.data.limit ?? 20;
                 // Over-fetch so that after chunk dedup we still have ~limit rows.
                 const smResults = await (0, memory_js_1.searchSupermemory)(parsed.data.query, Math.min(50, limit * 3));
@@ -487,7 +543,7 @@ async function handleVaultTool(name, args) {
                         const grouped = Array.from(groups.values())
                             .sort((a, b) => b.bestScore - a.bestScore)
                             .slice(0, limit);
-                        const header = `🔍 **Vault Search** [Semantic]: "${parsed.data.query}" - ${grouped.length} entry/entries`;
+                        const header = `🔍 **Vault Search**: "${parsed.data.query}" - ${grouped.length} entry/entries`;
                         const rows = grouped.map((g, i) => {
                             const score = g.bestScore ? ` ${(g.bestScore * 100).toFixed(0)}%` : "";
                             const chunkBadge = g.isVaultChunk && g.chunkHits > 1
@@ -498,7 +554,10 @@ async function handleVaultTool(name, args) {
                                 `   ${g.bestPreview}${g.bestPreview.length >= 200 ? "…" : ""}`,
                             ].join("\n");
                         });
-                        return { content: [{ type: "text", text: [header, "", ...rows].join("\n") }] };
+                        return {
+                            content: [{ type: "text", text: [header, "", ...rows].join("\n") }],
+                            structuredContent: buildVaultSearch(parsed.data.query, grouped.map((g) => ({ key: g.key, title: g.title, type: g.type, score: g.bestScore, preview: g.bestPreview }))),
+                        };
                     }
                 }
             }
@@ -514,14 +573,21 @@ async function handleVaultTool(name, args) {
             if (data.error)
                 return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
             const results = data.results ?? [];
-            if (!results.length)
-                return { content: [{ type: "text", text: `No vault entries found for: "${parsed.data.query}"` }] };
+            if (!results.length) {
+                return {
+                    content: [{ type: "text", text: `No vault entries found for: "${parsed.data.query}"` }],
+                    structuredContent: buildVaultSearch(parsed.data.query, []),
+                };
+            }
             const header = `🔍 **Vault Search**: "${parsed.data.query}" - ${results.length} result(s)`;
             const rows = results.map((r, i) => [
                 `${i + 1}. [\`${r.key}\`] **${r.title}**  (${r.type} · v${r.version})`,
                 `   ${r.preview}`,
             ].join("\n"));
-            return { content: [{ type: "text", text: [header, "", ...rows].join("\n") }] };
+            return {
+                content: [{ type: "text", text: [header, "", ...rows].join("\n") }],
+                structuredContent: buildVaultSearch(parsed.data.query, results),
+            };
         }
         case "vault_history": {
             const parsed = HistorySchema.safeParse(args);
@@ -712,7 +778,21 @@ async function handleVaultTool(name, args) {
                 : await (0, convex_js_1.callConvex)("/vault/delete", "POST", { key: parsed.data.key }, "vault_delete");
             if (data.error)
                 return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
-            return { content: [{ type: "text", text: `🗑️ Deleted: \`${parsed.data.key}\` (${data.versionsRemoved ?? 0} versions removed)` }] };
+            // vault_save mirrors non-credential entries into memory for search - a
+            // "PERMANENT... cannot be undone" delete that leaves that mirror intact
+            // is not actually permanent. Only relevant for the local memory-file
+            // backend (the hosted Convex path cleans its own memories table inside
+            // the /vault/delete mutation itself, same request, no separate call).
+            let memoriesRemoved = 0;
+            const localMem = (0, local_memory_js_1.getLocalMemoryConfig)();
+            if (localMem) {
+                memoriesRemoved = (0, local_memory_js_1.localMemoryDeleteByVaultKey)(localMem, parsed.data.key);
+            }
+            else if (typeof data.memoriesRemoved === "number") {
+                memoriesRemoved = data.memoriesRemoved;
+            }
+            const memoryNote = memoriesRemoved > 0 ? ` + ${memoriesRemoved} memory mirror${memoriesRemoved === 1 ? "" : "s"} removed` : "";
+            return { content: [{ type: "text", text: `🗑️ Deleted: \`${parsed.data.key}\` (${data.versionsRemoved ?? 0} versions removed${memoryNote})` }] };
         }
         case "vault_tag": {
             const parsed = TagSchema.safeParse(args);

package/dist/wallet.js

@@ -36,8 +36,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BASE_CHAIN_ID = exports.MEV_PROTECT_ENABLED = exports.BROADCAST_RPC = exports.BASE_RPC = void 0;
 exports.clearWalletCache = clearWalletCache;
 exports.getMachineKey = getMachineKey;
+exports.warnIfNoPassphrase = warnIfNoPassphrase;
 exports.getOrCreateWallet = getOrCreateWallet;
 exports.signRequest = signRequest;
+exports.waitForReceipt = waitForReceipt;
 exports.signAndBroadcast = signAndBroadcast;
 const ethers_1 = require("ethers");
 const fs = __importStar(require("fs"));
@@ -64,14 +66,75 @@ exports.MEV_PROTECT_ENABLED = !!process.env.FINCH_BROADCAST_RPC;
 exports.BASE_CHAIN_ID = 8453;
 const WALLET_DIR = path.join(os.homedir(), ".finch");
 const WALLET_FILE = path.join(WALLET_DIR, "wallet.json");
+// Per-install random secret folded into the no-passphrase key derivation
+// (see getMachineKey). Generated once via crypto.randomBytes and stored
+// 0600 next to the wallet - real entropy, unlike hostname/platform/arch
+// which are guessable/public and give an attacker who copies the wallet
+// file everything they need to also derive the key.
+const LOCAL_SECRET_FILE = path.join(WALLET_DIR, ".local-secret");
 let _cachedWallet = null;
 function clearWalletCache() { _cachedWallet = null; }
+function getOrCreateLocalSecret() {
+    try {
+        const existing = fs.readFileSync(LOCAL_SECRET_FILE, "utf8").trim();
+        if (existing)
+            return existing;
+    }
+    catch { /* doesn't exist yet, or unreadable - (re)create below */ }
+    const secret = crypto.randomBytes(32).toString("hex");
+    if (!fs.existsSync(WALLET_DIR))
+        fs.mkdirSync(WALLET_DIR, { recursive: true });
+    fs.writeFileSync(LOCAL_SECRET_FILE, secret, { mode: 0o600 });
+    return secret;
+}
 function getMachineKey() {
-    // If a passphrase is set, use it as the primary secret for stronger encryption.
-    // Without it, the key is derived from public machine info only - this is
-    // convenience encryption (prevents casual reads), not security against
-    // an attacker who has read access to both the file and system info.
+    // A passphrase is meant to make the wallet portable (move the encrypted
+    // file + set the same passphrase elsewhere and it still decrypts) - so when
+    // one is set, derive the key from ONLY the passphrase, no machine binding.
     const passphrase = process.env.FINCH_WALLET_PASSPHRASE ?? "";
+    if (passphrase) {
+        return crypto.createHash("sha256").update(passphrase).digest("hex").slice(0, 32);
+    }
+    // Without a passphrase, this is convenience-only encryption - it still
+    // can't stop an attacker who obtains BOTH files (the encrypted wallet and
+    // this local secret), the same as any locally-stored key material. What it
+    // does stop is the weaker, more common case this used to be vulnerable to:
+    // hostname/platform/arch alone are public/guessable, so a copy of just the
+    // wallet file (backup sync, stolen disk, malware scraping known paths) used
+    // to be enough to brute-force the key offline. Folding in a random,
+    // file-local secret means the wallet file alone is no longer sufficient.
+    return crypto
+        .createHash("sha256")
+        .update(getOrCreateLocalSecret() + os.hostname() + os.platform() + os.arch())
+        .digest("hex")
+        .slice(0, 32);
+}
+/** Pre-entropy-fix no-passphrase key: machine info only, no local secret.
+ *  Kept solely so wallets encrypted before this fix still open; migrated to
+ *  the new scheme in place on first successful decrypt, same pattern as
+ *  getLegacyMachineKey below. */
+function getLegacyMachineOnlyKey() {
+    return crypto
+        .createHash("sha256")
+        .update(os.hostname() + os.platform() + os.arch())
+        .digest("hex")
+        .slice(0, 32);
+}
+/**
+ * Pre-fix key derivation: always folded in machine info even when a
+ * passphrase was set, so a wallet encrypted before this fix can only ever be
+ * decrypted on the exact machine that created it - never portable. Kept
+ * solely so those existing wallets still open; getOrCreateWallet migrates
+ * them to the portable scheme in place on first successful decrypt.
+ *
+ * `passphrase` is a parameter, not read from env, because the whole point of
+ * this fallback is testing what the file was ACTUALLY encrypted with - which
+ * may not be today's FINCH_WALLET_PASSPHRASE. The most common case this
+ * exists for: a user who never set a passphrase before (so the file was
+ * encrypted with "" + machine info) setting one for the FIRST time just now -
+ * at that moment env has the new passphrase, but the file predates it.
+ */
+function getLegacyMachineKey(passphrase) {
     return crypto
         .createHash("sha256")
         .update(passphrase + os.hostname() + os.platform() + os.arch())
@@ -84,13 +147,34 @@ function warnIfNoPassphrase() {
         return;
     _passphraseWarned = true;
     // stderr only - stdout is reserved for MCP JSON-RPC framing when running as a server.
-    process.stderr.write("\n⚠️  FINCH_WALLET_PASSPHRASE is not set. Your Base mainnet wallet " +
-        `(${WALLET_FILE}) is encrypted with a key derived only from this machine's ` +
-        "hostname/platform/arch - low entropy, and crackable by anyone who copies the " +
-        "file (backup sync, stolen disk, malware). Set FINCH_WALLET_PASSPHRASE to a " +
-        "strong secret for real protection. This wallet holds real funds.\n\n");
+    process.stderr.write("\n⚠️  FINCH_WALLET_PASSPHRASE is not set. Your local wallet " +
+        `(${WALLET_FILE}, used on both Base and Robinhood Chain) is encrypted with a key derived from a random ` +
+        `per-install secret (${LOCAL_SECRET_FILE}) plus this machine's hostname/platform/arch. That stops the wallet ` +
+        "file alone from being crackable, but anyone who copies BOTH files together (backup sync, stolen disk, " +
+        "malware) still gets the wallet. Set FINCH_WALLET_PASSPHRASE to a strong secret you keep out of that backup " +
+        "for real protection. This wallet holds real funds.\n\n");
 }
+let _walletCreationPromise = null;
 async function getOrCreateWallet() {
+    if (_cachedWallet)
+        return _cachedWallet;
+    // In-process mutex: two concurrent first-run callers (before _cachedWallet
+    // is set) must not each independently generate + write their own random
+    // wallet - only one write can ever survive on disk, and the loser would go
+    // on signing in-memory with a keypair that no longer matches what's
+    // persisted, silently switching the user's wallet identity mid-session.
+    // Chain all concurrent first-run callers through one shared promise.
+    if (_walletCreationPromise)
+        return _walletCreationPromise;
+    _walletCreationPromise = loadOrCreateWallet();
+    try {
+        return await _walletCreationPromise;
+    }
+    finally {
+        _walletCreationPromise = null;
+    }
+}
+async function loadOrCreateWallet() {
     if (_cachedWallet)
         return _cachedWallet;
     warnIfNoPassphrase();
@@ -101,27 +185,101 @@ async function getOrCreateWallet() {
             _cachedWallet = wallet;
             return wallet;
         }
-        catch (err) {
-            // A wallet file already exists but couldn't be decrypted - this almost
-            // always means FINCH_WALLET_PASSPHRASE (or the machine info the key
-            // is derived from) doesn't match what encrypted it. Silently creating
-            // a fresh wallet here would overwrite the existing encrypted file,
-            // orphaning it and any funds it controls. Refuse instead.
-            throw new Error(`Could not decrypt existing wallet at ${WALLET_FILE}: ${err?.message ?? "unknown error"}\n\n` +
-                `This usually means FINCH_WALLET_PASSPHRASE doesn't match the passphrase ` +
-                `used when this wallet was encrypted (or this is a different machine). ` +
-                `Refusing to auto-create a replacement wallet, since that would silently ` +
-                `orphan the existing one and any funds it holds.\n\n` +
-                `If you're sure this wallet should be abandoned, move or delete ${WALLET_FILE} manually first.`);
+        catch (currentErr) {
+            // Fall back to the pre-fix machine-bound scheme, for wallets encrypted
+            // before passphrases became portable. Only relevant on the ORIGINAL
+            // machine (it still needs that machine's hostname/platform/arch) - it
+            // can't rescue a wallet file copied to a new machine from before this
+            // fix; there was no passphrase-only secret saved anywhere to recover.
+            //
+            // Try two legacy candidates: today's passphrase (in case it was already
+            // set when this file was encrypted) and "" (the common case - a user
+            // setting FINCH_WALLET_PASSPHRASE for the first time, whose existing
+            // file predates having any passphrase at all).
+            const legacyCandidates = [...new Set([process.env.FINCH_WALLET_PASSPHRASE ?? "", ""])];
+            let legacyWallet = null;
+            for (const candidate of legacyCandidates) {
+                try {
+                    legacyWallet = await ethers_1.ethers.Wallet.fromEncryptedJson(encrypted, getLegacyMachineKey(candidate));
+                    break;
+                }
+                catch { /* try next candidate */ }
+            }
+            if (legacyWallet) {
+                _cachedWallet = legacyWallet;
+                // Migrate in place to the portable scheme now that we've proven we
+                // hold the right key, so this only ever needs to happen once.
+                try {
+                    const migrated = await legacyWallet.encrypt(getMachineKey());
+                    fs.writeFileSync(WALLET_FILE, migrated, { mode: 0o600 });
+                    process.stderr.write(`\nMigrated ${WALLET_FILE} to the portable passphrase scheme.\n\n`);
+                }
+                catch {
+                    /* migration is best-effort - the legacy key still works next run either way */
+                }
+                return legacyWallet;
+            }
+            // Third tier: no passphrase ever set, and this wallet predates the fix
+            // that folds a random local secret into the no-passphrase key (it was
+            // encrypted with hostname/platform/arch alone). Try that exact old
+            // derivation before giving up.
+            if (!process.env.FINCH_WALLET_PASSPHRASE) {
+                try {
+                    const oldNoPassWallet = await ethers_1.ethers.Wallet.fromEncryptedJson(encrypted, getLegacyMachineOnlyKey());
+                    _cachedWallet = oldNoPassWallet;
+                    try {
+                        const migrated = await oldNoPassWallet.encrypt(getMachineKey());
+                        fs.writeFileSync(WALLET_FILE, migrated, { mode: 0o600 });
+                        process.stderr.write(`\nMigrated ${WALLET_FILE} to the higher-entropy no-passphrase scheme.\n\n`);
+                    }
+                    catch {
+                        /* migration is best-effort - the legacy key still works next run either way */
+                    }
+                    return oldNoPassWallet;
+                }
+                catch { /* not this scheme either - fall through to the hard failure below */ }
+            }
+            {
+                // A wallet file already exists but couldn't be decrypted under either
+                // scheme - this almost always means FINCH_WALLET_PASSPHRASE doesn't
+                // match what encrypted it, or this is a different machine and no
+                // passphrase was ever set. Silently creating a fresh wallet here
+                // would overwrite the existing encrypted file, orphaning it and any
+                // funds it controls. Refuse instead.
+                throw new Error(`Could not decrypt existing wallet at ${WALLET_FILE}: ${currentErr?.message ?? "unknown error"}\n\n` +
+                    `This usually means FINCH_WALLET_PASSPHRASE doesn't match the passphrase ` +
+                    `used when this wallet was encrypted, or this file was copied from a ` +
+                    `different machine and no passphrase was set when it was created (in ` +
+                    `which case the key was machine-bound and cannot be recovered elsewhere). ` +
+                    `Refusing to auto-create a replacement wallet, since that would silently ` +
+                    `orphan the existing one and any funds it holds.\n\n` +
+                    `If you're sure this wallet should be abandoned, move or delete ${WALLET_FILE} manually first.`);
+            }
         }
     }
     const wallet = ethers_1.ethers.Wallet.createRandom();
     if (!fs.existsSync(WALLET_DIR))
         fs.mkdirSync(WALLET_DIR, { recursive: true });
     const encrypted = await wallet.encrypt(getMachineKey());
-    fs.writeFileSync(WALLET_FILE, encrypted, { mode: 0o600 });
-    _cachedWallet = wallet;
-    return wallet;
+    try {
+        // Exclusive create ("wx") - guards the cross-process version of the race
+        // the in-process mutex above already closes: two separate `finch`
+        // invocations racing on the very first run, before this file exists.
+        fs.writeFileSync(WALLET_FILE, encrypted, { mode: 0o600, flag: "wx" });
+        _cachedWallet = wallet;
+        return wallet;
+    }
+    catch (writeErr) {
+        if (writeErr?.code !== "EEXIST")
+            throw writeErr;
+        // Another process won the race and created the file first. Use theirs -
+        // never sign with the wallet we generated in memory once it's clear it
+        // isn't the one actually persisted to disk.
+        const encryptedExisting = fs.readFileSync(WALLET_FILE, "utf8");
+        const existingWallet = await ethers_1.ethers.Wallet.fromEncryptedJson(encryptedExisting, getMachineKey());
+        _cachedWallet = existingWallet;
+        return existingWallet;
+    }
 }
 async function signRequest(toolName) {
     const wallet = await getOrCreateWallet();
@@ -161,6 +319,36 @@ async function broadcastTx(signedTx) {
         throw new Error(`broadcast failed: ${data.error.message}`);
     return data.result;
 }
+/**
+ * Poll for the mined receipt and report the ACTUAL on-chain outcome.
+ *
+ * eth_sendRawTransaction only confirms the mempool accepted the tx, not that
+ * it succeeded - a stale quote, slippage beyond the router's own guard, or an
+ * allowance edge case can all revert on-chain while still broadcasting fine.
+ * Callers must gate their success/failure message on this, not on
+ * signAndBroadcast() returning a hash.
+ */
+async function waitForReceipt(txHash, timeoutMs = 60000, pollMs = 2000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const receipt = await rpcPost("eth_getTransactionReceipt", [txHash]);
+            if (receipt) {
+                return {
+                    mined: true,
+                    ok: parseInt(receipt.status, 16) === 1,
+                    blockNumber: parseInt(receipt.blockNumber, 16),
+                    gasUsed: receipt.gasUsed ? BigInt(receipt.gasUsed).toString() : undefined,
+                };
+            }
+        }
+        catch {
+            /* transient RPC error - keep polling until timeout */
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    return { mined: false };
+}
 async function signAndBroadcast(wallet, txData) {
     let data = txData.data || "0x";
     if (txData.permit2?.eip712) {