@heuresis/mcp 1.0.0-rc.13 → 1.0.0-rc.14

package/dist/cli.js

@@ -101,21 +101,47 @@ function parseLoginFlags(argv) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-async function postJson(url, body) {
+// POST JSON with bounded retry + a per-attempt timeout. The device-pairing
+// endpoints sit behind the same Supabase edge as the auth token endpoint, so
+// they hit the same intermittently-dropped-TLS-handshake problem (see
+// gotrue.ts/postWithRetry): a lone fetch fails with "fetch failed" even though
+// a retry moments later lands. We retry transient transport errors and 5xx/429
+// here too; 4xx and the poll's own 202/410 signals are returned to the caller
+// unchanged. Throws the last transport error only after every attempt fails.
+async function postJson(url, body, { attempts = 4, perAttemptTimeoutMs = 8000 } = {}) {
     await ensureProxyAgent(log);
-    const res = await fetch(url, {
+    const init = {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(body),
-    });
-    let data = null;
-    try {
-        data = await res.json();
-    }
-    catch {
-        /* leave null */
+    };
+    let lastErr;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            const res = await fetch(url, { ...init, signal: AbortSignal.timeout(perAttemptTimeoutMs) });
+            if (res.status === 429 || (res.status >= 500 && res.status <= 599)) {
+                lastErr = new Error(`HTTP ${res.status}`); // transient — retry
+            }
+            else {
+                let data = null;
+                try {
+                    data = await res.json();
+                }
+                catch {
+                    /* leave null */
+                }
+                return { status: res.status, data };
+            }
+        }
+        catch (err) {
+            lastErr = err; // network drop / TLS reset / per-attempt timeout
+        }
+        if (attempt < attempts) {
+            // Backoff: 250ms, 500ms, 1000ms, … capped at 2s.
+            await sleep(Math.min(250 * 2 ** (attempt - 1), 2000));
+        }
     }
-    return { status: res.status, data };
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
 }
 export async function loginCommand(argv = []) {
     const opts = parseLoginFlags(argv);

package/dist/cloudClient.js

@@ -19,7 +19,13 @@
 // Polyfill global WebSocket on Node < 22 before any Supabase client is built.
 import './wsPolyfill.js';
 import { createClient } from '@supabase/supabase-js';
+import { writeCredentials } from './credentials.js';
 import { exchangeRefreshToken, signInWithPassword } from './gotrue.js';
+import { makeRetryingFetch } from './httpRetry.js';
+// Shared across every Supabase client we build: PostgREST queries and auth-js's
+// background refresh both go through this, so a flaky route can't hang or
+// one-shot-fail a data call (see httpRetry.ts).
+const retryingFetch = makeRetryingFetch();
 let cached = null;
 export class CloudAuthError extends Error {
     constructor(msg) {
@@ -42,6 +48,10 @@ async function seedClient(supabaseUrl, anonKey, session, userId) {
             autoRefreshToken: true,
             detectSessionInUrl: false,
         },
+        // Harden every PostgREST query / background refresh against the flaky
+        // route to the Supabase edge: bounded timeout + retry instead of an
+        // unbounded hang on a dropped TLS handshake.
+        global: { fetch: retryingFetch },
     });
     const { error } = await client.auth.setSession({
         access_token: session.access_token,
@@ -54,20 +64,53 @@ async function seedClient(supabaseUrl, anonKey, session, userId) {
     return cached;
 }
 /**
- * Build (or return cached) a Supabase client bound to the credentials on
- * disk. Bootstraps by exchanging the stored (rotating) refresh token. Throws
- * CloudAuthError if the refresh token has been revoked/rotated away.
+ * Persist a rotated refresh token back to ~/.heuresis/credentials.json.
  *
- * NOTE: a stored refresh token is single-use under Supabase rotation, so this
- * path is unsuitable for ephemeral environments that reuse the same persisted
- * credential across boots — use getCloudClientFromPassword() for those.
+ * GoTrue rotates the refresh token on every exchange and invalidates the old
+ * one. The bootstrap exchange — and supabase-js's later silent auto-refreshes —
+ * therefore make the on-disk token stale the moment we use it. If we never
+ * write the replacement back, the NEXT process start reads a spent token and
+ * fails with "Refresh Token Not Found", forcing a needless re-login (the MCP
+ * server is restarted on every Claude reconnect, so this bites constantly).
+ * Writing the new token back keeps the stored credential usable across
+ * restarts. Best-effort: a failed disk write must never break the live
+ * in-memory session, which is already valid for this process.
+ */
+async function persistRotatedToken(creds, newToken) {
+    if (!newToken || newToken === creds.refresh_token)
+        return;
+    try {
+        await writeCredentials({ ...creds, refresh_token: newToken });
+        creds.refresh_token = newToken; // keep the in-memory copy in sync
+    }
+    catch {
+        /* non-fatal — the in-memory session stays valid for this process */
+    }
+}
+/**
+ * Build (or return cached) a Supabase client bound to the credentials on
+ * disk. Bootstraps by exchanging the stored (rotating) refresh token, then
+ * persists the rotated replacement back to disk and keeps it in sync as
+ * supabase-js silently re-refreshes over the process lifetime — so the stored
+ * credential survives restarts. Throws CloudAuthError if the refresh token has
+ * been revoked/rotated away.
  */
 export async function getCloudClient(creds) {
     if (cached)
         return cached;
     try {
         const session = await exchangeRefreshToken(creds.supabase_url, creds.anon_key, creds.refresh_token);
-        return await seedClient(creds.supabase_url, creds.anon_key, session, creds.user_id);
+        // The exchange just consumed the on-disk token and rotated in a new one;
+        // persist it before anything else so a crash here can't strand us.
+        await persistRotatedToken(creds, session.refresh_token);
+        const result = await seedClient(creds.supabase_url, creds.anon_key, session, creds.user_id);
+        // Keep disk current as supabase-js auto-refreshes the token while we run.
+        result.client.auth.onAuthStateChange((event, s) => {
+            if ((event === 'TOKEN_REFRESHED' || event === 'SIGNED_IN') && s?.refresh_token) {
+                void persistRotatedToken(creds, s.refresh_token);
+            }
+        });
+        return result;
     }
     catch (err) {
         if (err instanceof CloudAuthError)

package/dist/gotrue.js

@@ -28,6 +28,43 @@ export class RefreshTokenError extends Error {
         this.name = 'RefreshTokenError';
     }
 }
+/**
+ * POST to a GoTrue token endpoint with bounded retry + a per-attempt timeout.
+ *
+ * Some networks have a flaky route to the Supabase edge: the TCP connect
+ * succeeds but the TLS handshake is intermittently dropped, so a single
+ * `fetch` fails ("fetch failed") even though a retry moments later lands. A
+ * lone request with no timeout/retry turns that transient drop into a fatal
+ * auth failure. We retry transient *transport* errors (the fetch throw) and
+ * 5xx/429 responses with short backoff; we do NOT retry 4xx (bad/expired
+ * token — retrying can't fix it), returning that Response to the caller for
+ * its normal error handling. Throws `RefreshTokenError` only after every
+ * attempt has failed to reach the endpoint.
+ */
+async function postWithRetry(url, init, { attempts = 4, perAttemptTimeoutMs = 8000 } = {}) {
+    let lastErr;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            const res = await fetch(url, { ...init, signal: AbortSignal.timeout(perAttemptTimeoutMs) });
+            // Retry only on transient server-side statuses; hand everything else back.
+            if (res.status === 429 || (res.status >= 500 && res.status <= 599)) {
+                lastErr = new Error(`HTTP ${res.status}`);
+            }
+            else {
+                return res;
+            }
+        }
+        catch (err) {
+            lastErr = err; // network drop / TLS reset / per-attempt timeout
+        }
+        if (attempt < attempts) {
+            // Backoff: 250ms, 500ms, 1000ms, ... capped at 2s.
+            const delay = Math.min(250 * 2 ** (attempt - 1), 2000);
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    throw new RefreshTokenError(`Could not reach the auth endpoint at ${url} after ${attempts} attempts: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+}
 /**
  * Exchange a refresh token for a fresh session via the GoTrue token endpoint:
  *
@@ -45,21 +82,15 @@ export async function exchangeRefreshToken(supabaseUrl, anonKey, refreshToken) {
             'The pairing response did not carry a usable token.');
     }
     const url = `${supabaseUrl.replace(/\/$/, '')}/auth/v1/token?grant_type=refresh_token`;
-    let res;
-    try {
-        res = await fetch(url, {
-            method: 'POST',
-            headers: {
-                apikey: anonKey,
-                Authorization: `Bearer ${anonKey}`,
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({ refresh_token: refreshToken }),
-        });
-    }
-    catch (err) {
-        throw new RefreshTokenError(`Could not reach the auth endpoint at ${url}: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const res = await postWithRetry(url, {
+        method: 'POST',
+        headers: {
+            apikey: anonKey,
+            Authorization: `Bearer ${anonKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ refresh_token: refreshToken }),
+    });
     let payload = null;
     try {
         payload = await res.json();
@@ -100,21 +131,15 @@ export async function signInWithPassword(supabaseUrl, anonKey, email, password)
         throw new RefreshTokenError('Headless sign-in needs both an email and a password (HEURESIS_EMAIL / HEURESIS_PASSWORD).');
     }
     const url = `${supabaseUrl.replace(/\/$/, '')}/auth/v1/token?grant_type=password`;
-    let res;
-    try {
-        res = await fetch(url, {
-            method: 'POST',
-            headers: {
-                apikey: anonKey,
-                Authorization: `Bearer ${anonKey}`,
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({ email, password }),
-        });
-    }
-    catch (err) {
-        throw new RefreshTokenError(`Could not reach the auth endpoint at ${url}: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const res = await postWithRetry(url, {
+        method: 'POST',
+        headers: {
+            apikey: anonKey,
+            Authorization: `Bearer ${anonKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ email, password }),
+    });
     let payload = null;
     try {
         payload = await res.json();

package/dist/httpRetry.js

@@ -0,0 +1,64 @@
+// Heuresis MCP — a retrying, timeout-bounded fetch for flaky networks.
+//
+// Some networks have an intermittently-broken route to the Supabase edge: the
+// TCP connect succeeds but the TLS handshake is sporadically dropped, so a lone
+// request fails with "fetch failed" (or, worse, a plain fetch with no timeout
+// hangs indefinitely) even though an identical request moments later lands.
+// This wrapper bounds each attempt with a timeout and retries transient
+// failures with exponential backoff. It is handed to supabase-js as its global
+// `fetch`, so every PostgREST query and auth-js background refresh inherits the
+// resilience — mirroring what gotrue.ts/postWithRetry and cli.ts/postJson do
+// for the calls they own.
+/**
+ * Build a `fetch`-compatible function with bounded retry + per-attempt timeout.
+ *
+ * Retry policy is idempotency-aware so we never risk double-applying a write:
+ *   - Transport errors (no response: TLS reset, connection drop, per-attempt
+ *     timeout) are retried for ANY method — the request almost certainly never
+ *     reached the server.
+ *   - 429 / 5xx are retried ONLY for idempotent methods (GET/HEAD). A POST/
+ *     PATCH/DELETE that got a 5xx may have been applied server-side, so we hand
+ *     that response back unretried and let the caller decide.
+ * A caller-supplied AbortSignal is honored: if it aborts, we stop immediately
+ * and never retry (the caller asked to cancel).
+ */
+export function makeRetryingFetch(opts = {}) {
+    const attempts = opts.attempts ?? 4;
+    const perAttemptTimeoutMs = opts.perAttemptTimeoutMs ?? 10_000;
+    return (async (input, init) => {
+        const method = (init?.method ?? 'GET').toUpperCase();
+        const idempotent = method === 'GET' || method === 'HEAD';
+        const callerSignal = init?.signal ?? undefined;
+        let lastErr;
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            if (callerSignal?.aborted)
+                throw callerSignal.reason ?? new Error('Aborted');
+            // Per-attempt timeout, combined with any caller signal so a caller-side
+            // cancel still propagates.
+            const timeout = AbortSignal.timeout(perAttemptTimeoutMs);
+            const signal = callerSignal ? AbortSignal.any([callerSignal, timeout]) : timeout;
+            try {
+                const res = await fetch(input, { ...init, signal });
+                if (res.status === 429 || (res.status >= 500 && res.status <= 599)) {
+                    if (!idempotent)
+                        return res; // don't retry a non-idempotent server error
+                    lastErr = new Error(`HTTP ${res.status}`);
+                }
+                else {
+                    return res;
+                }
+            }
+            catch (err) {
+                // A caller-initiated abort is terminal — surface it, don't retry.
+                if (callerSignal?.aborted)
+                    throw err;
+                lastErr = err; // transport error / per-attempt timeout — retry
+            }
+            if (attempt < attempts) {
+                // Backoff: 250ms, 500ms, 1000ms, … capped at 2s.
+                await new Promise((r) => setTimeout(r, Math.min(250 * 2 ** (attempt - 1), 2000)));
+            }
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    });
+}

package/dist/prompt/compose.js

@@ -8,31 +8,31 @@
 // target, knowledge pool, operator, plus the operator-specific inputs block.
 // File-context retrieval is a separate tool (find_in_files) that ships in
 // Agent B's tool-parity wave; not folded in here.
-const RESPONSE_TEMPLATE = `{
-  "partitions": [
-    {
-      "label": "STANDALONE concept title — 2–5 words, ≤ 60 chars, NO parent prefix, no trailing period",
-      "description": "1–2 sentences, ≤ 280 chars",
-      "partitionAttribute": "≤ 5 words for the distinguishing attribute",
-      "rationale": "1–3 sentences citing the operator and any K used",
-      "kReferences": ["k_id_or_empty"],
-      "selfCritique": "main weakness or assumption",
-      "children": [
-        {
-          "label": "STANDALONE sub-concept title — same rules; do NOT prefix with this partition's label either",
-          "description": "1–2 sentences, ≤ 280 chars",
-          "partitionAttribute": "≤ 5 words",
-          "rationale": "1–3 sentences",
-          "kReferences": [],
-          "selfCritique": "main weakness or assumption"
-        }
-      ]
-    }
-  ],
-  "newKnowledgeProposed": [
-    { "title": "fact title", "body": "1–2 sentences", "tags": ["tag1"] }
-  ],
-  "operatorNotes": "one line on how the operator fit (optional)"
+const RESPONSE_TEMPLATE = `{
+  "partitions": [
+    {
+      "label": "STANDALONE concept title — 2–5 words, ≤ 60 chars, NO parent prefix, no trailing period",
+      "description": "1–2 sentences, ≤ 280 chars",
+      "partitionAttribute": "≤ 5 words for the distinguishing attribute",
+      "rationale": "1–3 sentences citing the operator and any K used",
+      "kReferences": ["k_id_or_empty"],
+      "selfCritique": "main weakness or assumption",
+      "children": [
+        {
+          "label": "STANDALONE sub-concept title — same rules; do NOT prefix with this partition's label either",
+          "description": "1–2 sentences, ≤ 280 chars",
+          "partitionAttribute": "≤ 5 words",
+          "rationale": "1–3 sentences",
+          "kReferences": [],
+          "selfCritique": "main weakness or assumption"
+        }
+      ]
+    }
+  ],
+  "newKnowledgeProposed": [
+    { "title": "fact title", "body": "1–2 sentences", "tags": ["tag1"] }
+  ],
+  "operatorNotes": "one line on how the operator fit (optional)"
 }`;
 function pathBlock(path) {
     return path
@@ -70,11 +70,11 @@ function contradictionBlock(c) {
     const principles = c.principles
         .map((p) => `  - #${p.num} ${p.name}: ${p.doctrine}`)
         .join('\n');
-    return `<contradiction>
-  improving: ${c.improvingName}
-  worsening: ${c.worseningName}
-  matrix_principles:
-${principles}
+    return `<contradiction>
+  improving: ${c.improvingName}
+  worsening: ${c.worseningName}
+  matrix_principles:
+${principles}
 </contradiction>`;
 }
 export function composePrompt(input) {
@@ -92,50 +92,50 @@ export function composePrompt(input) {
     const contradictionXml = operator.family === 'CONTRADICTION' && contradiction
         ? `\n${contradictionBlock(contradiction)}\n`
         : '';
-    return `You are assisting an inventive design session structured by C-K theory. The user is growing a graph of concepts (C) drawing on a pool of validated knowledge (K). You will generate a set of new partitions of the TARGET concept by applying the requested operator from ASIT/TRIZ.
-
-<brief>
-${project.brief}
-</brief>
-
-<concept_path_root_to_target>
-${pathBlock(ancestry)}
-</concept_path_root_to_target>
-
-<target_concept>
-id: ${target.id}
-label: ${target.label}
-description: ${target.description || '(no description)'}
-notes: ${target.notes || '(none)'}
-</target_concept>
-
-<knowledge_pool>
-${knowledgeBlock(knowledge)}
-</knowledge_pool>
-
-<operator>
-family: ${operator.family}
-key: ${operator.key}
-name: ${operator.name}
-doctrine: ${operator.doctrine}
-</operator>
-${inputsXml}${branchXml}${contradictionXml}${angleBlock}
-<instructions>
-${operator.promptFragment}
-
-Rules:
-- Produce 3–5 partitions at the top level, each genuinely distinct, each adding a clear new attribute to the TARGET concept. (The optional \`children\` array below adds depth-2 nodes; it does NOT count toward the 3–5 top-level requirement.)
-- Labels MUST be STANDALONE concept titles. Do NOT prefix labels with the parent concept's label. For example, if the parent is "Test", do NOT write labels like "Test by destruction" or "Test for X" — just write "Destruction" or "X". The label should make sense on its own; the parent context is implicit from the graph structure. This rule applies to EVERY label in the response, including children (a child's label must not contain its immediate parent partition's label either).
-- Labels MUST be short: 2–5 words, ≤ 60 characters, no trailing punctuation. The label is a concept title, not a sentence. Put long-form prose in description/rationale, not in label.
-- Each partition MAY optionally include a \`children\` array of 1–4 sub-partitions, when the partition naturally decomposes further into a clearly distinct sub-axis. Children follow the same shape (label, description, partitionAttribute, rationale, kReferences, selfCritique). Do NOT nest beyond one level — a child must NEVER have its own \`children\` array. Omit \`children\` entirely when no useful sub-decomposition exists; do not pad.
-- Stay faithful to the operator's doctrine. If the operator forbids alien components (ASIT closed-world), do not introduce them.
-- For each partition, cite by id any knowledge item from <knowledge_pool> you actually used in kReferences. Empty array if none.
-- Use selfCritique to surface the strongest assumption or risk in that partition (do not flatter the idea).
-- If you needed a fact you did not have, propose it via newKnowledgeProposed (1–3 items max). Do NOT invent specific numbers as facts; phrase as questions to verify.
-- Output ONLY a single JSON object, matching this shape exactly. No prose before or after, no markdown fences.
-</instructions>
-
-<response_shape>
-${RESPONSE_TEMPLATE}
+    return `You are assisting an inventive design session structured by C-K theory. The user is growing a graph of concepts (C) drawing on a pool of validated knowledge (K). You will generate a set of new partitions of the TARGET concept by applying the requested operator from ASIT/TRIZ.
+
+<brief>
+${project.brief}
+</brief>
+
+<concept_path_root_to_target>
+${pathBlock(ancestry)}
+</concept_path_root_to_target>
+
+<target_concept>
+id: ${target.id}
+label: ${target.label}
+description: ${target.description || '(no description)'}
+notes: ${target.notes || '(none)'}
+</target_concept>
+
+<knowledge_pool>
+${knowledgeBlock(knowledge)}
+</knowledge_pool>
+
+<operator>
+family: ${operator.family}
+key: ${operator.key}
+name: ${operator.name}
+doctrine: ${operator.doctrine}
+</operator>
+${inputsXml}${branchXml}${contradictionXml}${angleBlock}
+<instructions>
+${operator.promptFragment}
+
+Rules:
+- Produce 3–5 partitions at the top level, each genuinely distinct, each adding a clear new attribute to the TARGET concept. (The optional \`children\` array below adds depth-2 nodes; it does NOT count toward the 3–5 top-level requirement.)
+- Labels MUST be STANDALONE concept titles. Do NOT prefix labels with the parent concept's label. For example, if the parent is "Test", do NOT write labels like "Test by destruction" or "Test for X" — just write "Destruction" or "X". The label should make sense on its own; the parent context is implicit from the graph structure. This rule applies to EVERY label in the response, including children (a child's label must not contain its immediate parent partition's label either).
+- Labels MUST be short: 2–5 words, ≤ 60 characters, no trailing punctuation. The label is a concept title, not a sentence. Put long-form prose in description/rationale, not in label.
+- Each partition MAY optionally include a \`children\` array of 1–4 sub-partitions, when the partition naturally decomposes further into a clearly distinct sub-axis. Children follow the same shape (label, description, partitionAttribute, rationale, kReferences, selfCritique). Do NOT nest beyond one level — a child must NEVER have its own \`children\` array. Omit \`children\` entirely when no useful sub-decomposition exists; do not pad.
+- Stay faithful to the operator's doctrine. If the operator forbids alien components (ASIT closed-world), do not introduce them.
+- For each partition, cite by id any knowledge item from <knowledge_pool> you actually used in kReferences. Empty array if none.
+- Use selfCritique to surface the strongest assumption or risk in that partition (do not flatter the idea).
+- If you needed a fact you did not have, propose it via newKnowledgeProposed (1–3 items max). Do NOT invent specific numbers as facts; phrase as questions to verify.
+- Output ONLY a single JSON object, matching this shape exactly. No prose before or after, no markdown fences.
+</instructions>
+
+<response_shape>
+${RESPONSE_TEMPLATE}
 </response_shape>`;
 }

package/dist/proxy.js

@@ -1,43 +1,77 @@
-// Heuresis MCP — proxy wiring for Node's global fetch dispatcher.
+// Heuresis MCP — global fetch dispatcher wiring (proxy + IPv4 preference).
 //
 // Node 18-22's undici does NOT auto-honor HTTPS_PROXY / HTTP_PROXY (Node 24+
 // does). Without this, every outbound fetch fails with "fetch failed" on
 // networks that require an egress proxy — both the device-pairing + GoTrue
 // refresh calls in the CLI and the SupabaseClient's PostgREST queries in the
-// running MCP server. We install an undici ProxyAgent as the global
-// dispatcher once, at process start.
+// running MCP server. We install an undici ProxyAgent as the global dispatcher
+// once, at process start.
 //
-// Idempotent across the whole process (module-level flag) and a no-op when no
-// proxy var is set, so it is safe to call from every entry point.
+// When NO proxy is set we STILL install a custom global dispatcher: an Agent
+// that resolves hostnames IPv4-only. On networks with a dead / black-holed
+// IPv6 DNS resolver (e.g. a stale ISP IPv6 nameserver handed out over DHCPv6),
+// a default dual-stack getaddrinfo issues BOTH an A and a AAAA query and waits
+// for both — the AAAA query stalls ~4-8s or times out against the dead resolver
+// before the (instant) A answer can be used, so every fetch intermittently
+// hangs even though IPv4 connectivity is perfectly fine. Forcing family:4 skips
+// the AAAA query entirely. This is safe for this client: every endpoint it
+// talks to (Supabase behind Cloudflare) is IPv4-reachable — in fact the
+// Supabase host publishes no AAAA record at all.
+//
+// Idempotent across the whole process (module-level flag) and safe to call from
+// every entry point.
 //
 // NOTE: this only covers `fetch` (PostgREST + auth). The Realtime websocket
-// uses a separate transport that the global dispatcher does not touch; live
-// sync behind a strict proxy is a known follow-up, but it is best-effort and
-// fire-and-forget, so it never blocks tool calls.
-let proxyAgentInstalled = false;
+// uses a separate transport that the global dispatcher does not touch.
+import { lookup } from 'node:dns';
+let dispatcherInstalled = false;
 /**
- * Route Node's global `fetch` through HTTPS_PROXY / HTTP_PROXY when set.
- * Pass a logger to surface the routing decision (the CLI logs to stderr; the
- * server passes console.error). Resolves once the dispatcher is in place.
+ * Install the process-wide undici dispatcher for Node's global `fetch`:
+ * a ProxyAgent when HTTPS_PROXY/HTTP_PROXY is set, otherwise an IPv4-preferring
+ * Agent (see header for why). Pass a logger to surface the routing decision
+ * (the CLI logs to stderr; the server passes console.error). Idempotent.
  */
 export async function ensureProxyAgent(log = () => { }) {
-    if (proxyAgentInstalled)
+    if (dispatcherInstalled)
         return;
-    proxyAgentInstalled = true;
+    dispatcherInstalled = true;
     const proxyUrl = process.env.HTTPS_PROXY ||
         process.env.https_proxy ||
         process.env.HTTP_PROXY ||
         process.env.http_proxy;
-    if (!proxyUrl)
-        return;
     try {
-        // Dynamic import keeps undici off the cold-start path when no proxy is in
-        // play. It's a direct dependency, so this resolves.
-        const { ProxyAgent, setGlobalDispatcher } = await import('undici');
-        setGlobalDispatcher(new ProxyAgent(proxyUrl));
-        log(`(routing through proxy ${proxyUrl})`);
+        // undici is a direct dependency, so this resolves. Dynamic import keeps it
+        // off the cold-start path until we actually configure the dispatcher.
+        const { Agent, ProxyAgent, setGlobalDispatcher } = await import('undici');
+        if (proxyUrl) {
+            // Behind a proxy the target's DNS is resolved by the proxy, so the IPv6
+            // stall does not apply locally — just route through the proxy.
+            setGlobalDispatcher(new ProxyAgent(proxyUrl));
+            log(`(routing through proxy ${proxyUrl})`);
+        }
+        else {
+            // No proxy: pin IPv4 to dodge two distinct flaky-network failure modes
+            // that both manifest as intermittent ~4-8s stalls to the Supabase host:
+            //   1. A dead/stalling IPv6 DNS resolver — a default dual-stack lookup
+            //      issues a AAAA query that hangs before the instant A answer is used.
+            //   2. Node/undici's Happy-Eyeballs (autoSelectFamily) racing the
+            //      connection, which on some networks wedges the handshake ~50% of
+            //      the time to this host even when each IP is individually healthy
+            //      (verified: both Cloudflare IPs 6/6 when pinned, but 3/6 with the
+            //      race on). Disabling it + forcing family:4 is reliably 8/8.
+            setGlobalDispatcher(new Agent({
+                connect: {
+                    autoSelectFamily: false,
+                    // Pin the address family to IPv4 (also skips the AAAA query) while
+                    // preserving undici's other lookup options (e.g. `all`). The cast
+                    // sidesteps dns.lookup's overload union — we faithfully forward
+                    // undici's own callback, whatever result shape it expects.
+                    lookup: (hostname, options, callback) => lookup(hostname, { ...options, family: 4 }, callback),
+                },
+            }));
+        }
     }
     catch (err) {
-        log(`(could not configure proxy ${proxyUrl}: ${err instanceof Error ? err.message : String(err)})`);
+        log(`(could not configure fetch dispatcher: ${err instanceof Error ? err.message : String(err)})`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heuresis/mcp",
-  "version": "1.0.0-rc.13",
+  "version": "1.0.0-rc.14",
   "mcpName": "io.github.ToremLabs/heuresis",
   "description": "Cloud-authenticated Model Context Protocol server for a Heuresis workspace. Logs into the user's Heuresis account and lets any MCP client (Claude Desktop, Claude Code, Cursor, custom agents) read and write the same workspace the webapp uses. 31 data tools, 3 operator tools (Branch/Matrix/C-K/ASIT/TRIZ/Free/Combine/Explore), and live Realtime change subscriptions.",
   "type": "module",