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

package/README.md

@@ -7,7 +7,7 @@ account, talks to the same Supabase project the webapp talks to, and
 respects the same RLS. Webapp and MCP are two front-ends to one cloud
 workspace.
 
-Current version: `1.0.0-rc.12`.
+Current version: `1.0.0-rc.13`.
 
 ## Install
 
@@ -89,6 +89,36 @@ npx -y @heuresis/mcp --no-realtime            # boot the server with live sync o
 npx -y @heuresis/mcp --realtime               # re-enable live sync
 ```
 
+## Headless mode (CI, cloud agents, disposable containers)
+
+Device pairing writes a **refresh token** to disk. That works great on a
+personal machine, but it does **not** survive disposable/ephemeral
+environments (CI runners, cloud agent containers, "Claude Code on the web"):
+the filesystem is wiped between runs, and a Supabase refresh token is
+**single-use under rotation** — so a token baked into config dies after the
+first session.
+
+For those environments, skip pairing and let the server **sign in fresh on
+every boot** from your account email + password (a password is not consumed on
+use, so it works forever with no re-pairing). Set three env vars:
+
+```bash
+HEURESIS_EMAIL=you@example.com          # your Heuresis account email
+HEURESIS_PASSWORD=your-account-password # secret — store it in a secrets manager
+HEURESIS_ANON_KEY=sb_publishable_...    # project anon/publishable key (public, not a secret)
+# optional: HEURESIS_SUPABASE_URL=...   # defaults to the production project
+```
+
+When `HEURESIS_EMAIL` + `HEURESIS_PASSWORD` are present they take precedence
+over any `credentials.json`, and the MCP server authenticates per boot — no
+device link required. Requirements:
+
+- Email + password sign-in must be enabled for the Supabase project, and the
+  account must have a password set (passwordless / magic-link-only accounts
+  need a password added first).
+- Treat `HEURESIS_PASSWORD` as a secret. Prefer a dedicated account if your
+  environment can only expose env vars that are visible to its users.
+
 ## Live sync
 
 When the MCP boots in cloud mode it subscribes to the workspace over

package/dist/cli.js

@@ -35,7 +35,7 @@ import { ensureProxyAgent } from './proxy.js';
 // allow HEURESIS_SUPABASE_URL to override which Supabase project the CLI
 // talks to (e.g. a staging instance). Both default to production.
 const DEFAULT_DEVICE_BASE_URL = 'https://heuresis.app';
-const DEFAULT_SUPABASE_URL = 'https://wpgniquyuppljeqkedqh.supabase.co';
+export const DEFAULT_SUPABASE_URL = 'https://wpgniquyuppljeqkedqh.supabase.co';
 const POLL_INTERVAL_MS = 5_000;
 const POLL_TIMEOUT_MS = 15 * 60 * 1_000;
 function log(...args) {
@@ -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 { exchangeRefreshToken } from './gotrue.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) {
@@ -28,14 +34,12 @@ export class CloudAuthError extends Error {
     }
 }
 /**
- * Build (or return cached) a Supabase client bound to the credentials on
- * disk. Throws CloudAuthError if no credentials exist or if the refresh
- * token has been revoked.
+ * Create a headless Supabase client and seed it with an already-obtained
+ * GoTrue session, so every subsequent PostgREST call carries the user's JWT
+ * and supabase-js keeps the in-memory access token alive. Caches the result.
  */
-export async function getCloudClient(creds) {
-    if (cached)
-        return cached;
-    const client = createClient(creds.supabase_url, creds.anon_key, {
+async function seedClient(supabaseUrl, anonKey, session, userId) {
+    const client = createClient(supabaseUrl, anonKey, {
         auth: {
             // Headless: no localStorage, no URL detection, no auto-refresh
             // listeners writing to disk. The library still auto-refreshes the
@@ -44,29 +48,96 @@ export async function getCloudClient(creds) {
             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 },
     });
-    // Bootstrap the session: exchange the stored refresh token for a fresh
-    // session directly against GoTrue, then seed supabase-js with the REAL
-    // tokens so every subsequent PostgREST call carries the user's JWT and
-    // auto-refresh keeps it alive.
+    const { error } = await client.auth.setSession({
+        access_token: session.access_token,
+        refresh_token: session.refresh_token,
+    });
+    if (error) {
+        throw new CloudAuthError(`Failed to seed Heuresis session: ${error.message}.`);
+    }
+    cached = { client, userId };
+    return cached;
+}
+/**
+ * Persist a rotated refresh token back to ~/.heuresis/credentials.json.
+ *
+ * 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);
-        const { error } = await client.auth.setSession({
-            access_token: session.access_token,
-            refresh_token: session.refresh_token,
+        // 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);
+            }
         });
-        if (error) {
-            throw new CloudAuthError(`Failed to seed Heuresis session: ${error.message}. ` +
-                'Run `npx -y -p @heuresis/mcp heuresis-mcp login` to re-authenticate.');
-        }
+        return result;
     }
     catch (err) {
         if (err instanceof CloudAuthError)
             throw err;
         throw new CloudAuthError(`Failed to refresh Heuresis session: ${err instanceof Error ? err.message : String(err)}. Run \`npx -y -p @heuresis/mcp heuresis-mcp login\` to re-authenticate.`);
     }
-    cached = { client, userId: creds.user_id };
-    return cached;
+}
+/**
+ * Build (or return cached) a Supabase client by signing in fresh with an
+ * email + password. Because a password is not consumed on use, this works
+ * durably across disposable/ephemeral sessions that re-authenticate on every
+ * boot — no persisted, rotating refresh token required. Throws CloudAuthError
+ * on bad credentials or if password sign-in is disabled for the project.
+ */
+export async function getCloudClientFromPassword(supabaseUrl, anonKey, email, password) {
+    if (cached)
+        return cached;
+    try {
+        const session = await signInWithPassword(supabaseUrl, anonKey, email, password);
+        const userId = session.user?.id ?? '(unknown)';
+        return await seedClient(supabaseUrl, anonKey, session, userId);
+    }
+    catch (err) {
+        if (err instanceof CloudAuthError)
+            throw err;
+        throw new CloudAuthError(`Headless email/password sign-in failed: ${err instanceof Error ? err.message : String(err)}. Check HEURESIS_EMAIL / HEURESIS_PASSWORD / HEURESIS_ANON_KEY.`);
+    }
 }
 /** Clear the cached client. Used after logout. */
 export function resetCloudClient() {

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,64 @@ 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;
+    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 {
-        res = await fetch(url, {
-            method: 'POST',
-            headers: {
-                apikey: anonKey,
-                Authorization: `Bearer ${anonKey}`,
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({ refresh_token: refreshToken }),
-        });
+        payload = await res.json();
+    }
+    catch {
+        /* leave null — handled below */
+    }
+    if (!res.ok) {
+        const err = payload;
+        const detail = err?.error_description ?? err?.msg ?? err?.error ?? err?.message ?? `HTTP ${res.status}`;
+        throw new RefreshTokenError(`Token refresh failed (HTTP ${res.status}): ${detail}`);
+    }
+    const session = payload;
+    if (!session || !session.access_token || !session.refresh_token) {
+        const keys = session && typeof session === 'object'
+            ? Object.keys(session).join(', ') || '(empty object)'
+            : '(no JSON body)';
+        throw new RefreshTokenError(`Token refresh succeeded (HTTP ${res.status}) but the response is missing ` +
+            `access_token/refresh_token. Response keys: [${keys}].`);
     }
-    catch (err) {
-        throw new RefreshTokenError(`Could not reach the auth endpoint at ${url}: ${err instanceof Error ? err.message : String(err)}`);
+    return session;
+}
+/**
+ * Sign in with an email + password directly against the GoTrue token endpoint:
+ *
+ *   POST `${supabaseUrl}/auth/v1/token?grant_type=password`
+ *   headers: { apikey, Authorization: Bearer <anon>, Content-Type: application/json }
+ *   body:    { email, password }
+ *
+ * Unlike a refresh token, a password is NOT consumed on use, so this is the
+ * right primitive for headless, ephemeral environments (e.g. cloud agent
+ * containers) that re-authenticate from scratch on every boot. Returns the
+ * full session (access_token + refresh_token + user). Throws
+ * `RefreshTokenError` with an actionable message on any failure.
+ */
+export async function signInWithPassword(supabaseUrl, anonKey, email, password) {
+    if (!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`;
+    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();
@@ -70,14 +150,16 @@ export async function exchangeRefreshToken(supabaseUrl, anonKey, refreshToken) {
     if (!res.ok) {
         const err = payload;
         const detail = err?.error_description ?? err?.msg ?? err?.error ?? err?.message ?? `HTTP ${res.status}`;
-        throw new RefreshTokenError(`Token refresh failed (HTTP ${res.status}): ${detail}`);
+        throw new RefreshTokenError(`Email/password sign-in failed (HTTP ${res.status}): ${detail}. ` +
+            'Check HEURESIS_EMAIL / HEURESIS_PASSWORD, and that email+password sign-in is ' +
+            'enabled for the Supabase project.');
     }
     const session = payload;
     if (!session || !session.access_token || !session.refresh_token) {
         const keys = session && typeof session === 'object'
             ? Object.keys(session).join(', ') || '(empty object)'
             : '(no JSON body)';
-        throw new RefreshTokenError(`Token refresh succeeded (HTTP ${res.status}) but the response is missing ` +
+        throw new RefreshTokenError(`Sign-in succeeded (HTTP ${res.status}) but the response is missing ` +
             `access_token/refresh_token. Response keys: [${keys}].`);
     }
     return session;

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/index.js

@@ -23,9 +23,9 @@ import { HeuresisStore } from './store.js';
 import { getConcept as legacyGetConcept, getConceptInput as legacyGetConceptInput, getProjectGraph as legacyGetProjectGraph, getProjectGraphInput as legacyGetProjectGraphInput, getSubtree as legacyGetSubtree, getSubtreeInput as legacyGetSubtreeInput, getWorkspaceSummary as legacyGetWorkspaceSummary, getWorkspaceSummaryInput as legacyGetWorkspaceSummaryInput, listProjects as legacyListProjects, listProjectsInput as legacyListProjectsInput, listRecentDecisions as legacyListRecentDecisions, listRecentDecisionsInput as legacyListRecentDecisionsInput, searchConcepts as legacySearchConcepts, searchConceptsInput as legacySearchConceptsInput, } from './tools.js';
 import { CLOUD_TOOLS } from './cloudTools.js';
 import { readCredentials } from './credentials.js';
-import { CloudAuthError, getCloudClient } from './cloudClient.js';
+import { CloudAuthError, getCloudClient, getCloudClientFromPassword } from './cloudClient.js';
 import { ensureProxyAgent } from './proxy.js';
-import { helpCommand, loginCommand, logoutCommand, whoamiCommand, } from './cli.js';
+import { DEFAULT_SUPABASE_URL, helpCommand, loginCommand, logoutCommand, whoamiCommand, } from './cli.js';
 import { readRealtimeFlag, resolveSubscriptionWorkspaceId, startRealtimeSubscription, stripRealtimeFlags, } from './realtime.js';
 const VERSION = '0.2.0-alpha';
 const MAX_RESULT_CHARS = 50_000;
@@ -46,6 +46,21 @@ function makeCloudTools(getClient, operatorTools) {
         handler: async (args) => t.handler(await getClient(), args),
     }));
 }
+// Phase 19.5 — try to load LLM-backed Operator tools. The module may be absent
+// or export nothing; in that case we fall back to just the Phase 19.4 parity
+// set. Wrapping the dynamic import in try/catch keeps the server starting
+// cleanly either way.
+async function loadOperatorTools() {
+    try {
+        const mod = (await import('./cloudOperators.js').catch(() => null));
+        if (mod && Array.isArray(mod.OPERATOR_TOOLS))
+            return mod.OPERATOR_TOOLS;
+    }
+    catch {
+        /* fall through to empty */
+    }
+    return [];
+}
 function makeLegacySnapshotTools(store) {
     // LEGACY FALLBACK — removed after 19.7. Read-only, no auth, snapshot file.
     return [
@@ -99,38 +114,59 @@ async function runServer() {
     await ensureProxyAgent(console.error);
     const creds = await readCredentials();
     const snapshotEnv = process.env.HEURESIS_SNAPSHOT;
+    // Headless credential (durable across ephemeral/disposable sessions): when
+    // HEURESIS_EMAIL + HEURESIS_PASSWORD are set, the server signs in fresh on
+    // every boot. Unlike a persisted refresh token — which is single-use under
+    // Supabase rotation and dies after one session — a password is not consumed,
+    // so this survives container resets with zero re-pairing. It takes
+    // precedence over a (possibly stale) credentials.json.
+    const headlessEmail = process.env.HEURESIS_EMAIL?.trim();
+    const headlessPassword = process.env.HEURESIS_PASSWORD;
     let tools;
     let modeBanner;
-    if (creds) {
-        // CLOUD mode.
-        const getClient = async () => {
+    // Single cloud client getter, shared by the tool handlers and the realtime
+    // subscription. null in legacy snapshot / unconfigured modes.
+    let cloudGetClient = null;
+    if (headlessEmail && headlessPassword) {
+        // CLOUD mode — headless email/password sign-in (recommended for cloud /
+        // disposable containers).
+        const supabaseUrl = process.env.HEURESIS_SUPABASE_URL?.trim() || DEFAULT_SUPABASE_URL;
+        const anonKey = process.env.HEURESIS_ANON_KEY?.trim();
+        if (!anonKey) {
+            console.error([
+                '[heuresis-mcp] HEURESIS_EMAIL/HEURESIS_PASSWORD are set but HEURESIS_ANON_KEY is missing.',
+                'Set HEURESIS_ANON_KEY to your project anon/publishable key (it is public, not a secret).',
+            ].join('\n'));
+            process.exit(1);
+        }
+        cloudGetClient = async () => {
             try {
-                const { client } = await getCloudClient(creds);
+                const { client } = await getCloudClientFromPassword(supabaseUrl, anonKey, headlessEmail, headlessPassword);
                 return client;
             }
             catch (err) {
-                if (err instanceof CloudAuthError) {
+                if (err instanceof CloudAuthError)
                     throw new Error(err.message);
-                }
                 throw err;
             }
         };
-        // Phase 19.5 — try to load Operator tools. The module may not exist
-        // yet at build time (Agent A ships it in a parallel pass); if it's
-        // missing OR exports nothing, we fall back to just the Phase 19.4
-        // parity set. Wrapping the dynamic import in try/catch keeps the
-        // server starting cleanly in either case.
-        let operatorTools = [];
-        try {
-            const mod = (await import('./cloudOperators.js').catch(() => null));
-            if (mod && Array.isArray(mod.OPERATOR_TOOLS)) {
-                operatorTools = mod.OPERATOR_TOOLS;
+        tools = makeCloudTools(cloudGetClient, await loadOperatorTools());
+        modeBanner = `cloud-authenticated (headless ${headlessEmail}; ${tools.length} tools)`;
+    }
+    else if (creds) {
+        // CLOUD mode — persisted device credential (refresh-token bootstrap).
+        cloudGetClient = async () => {
+            try {
+                const { client } = await getCloudClient(creds);
+                return client;
             }
-        }
-        catch {
-            operatorTools = [];
-        }
-        tools = makeCloudTools(getClient, operatorTools);
+            catch (err) {
+                if (err instanceof CloudAuthError)
+                    throw new Error(err.message);
+                throw err;
+            }
+        };
+        tools = makeCloudTools(cloudGetClient, await loadOperatorTools());
         modeBanner = `cloud-authenticated (user_id ${creds.user_id}, device ${creds.device_name}; ${tools.length} tools)`;
     }
     else if (snapshotEnv || hasDefaultSnapshot()) {
@@ -144,9 +180,15 @@ async function runServer() {
         console.error([
             '[heuresis-mcp] Not configured.',
             '',
-            'To use cloud mode (recommended):',
+            'To use cloud mode on a personal machine (device pairing):',
             '  npx -y -p @heuresis/mcp heuresis-mcp login',
             '',
+            'To use cloud mode headlessly (CI / cloud agents / disposable containers),',
+            'set these env vars so the server signs in fresh on every boot:',
+            '  HEURESIS_EMAIL      your Heuresis account email',
+            '  HEURESIS_PASSWORD   your Heuresis account password',
+            '  HEURESIS_ANON_KEY   your project anon/publishable key (public, not a secret)',
+            '',
             'To use legacy snapshot mode (deprecated, removed after 19.7):',
             '  HEURESIS_SNAPSHOT=/path/to/export.json npx @heuresis/mcp',
             '',
@@ -210,7 +252,7 @@ async function runServer() {
     console.error(`[heuresis-mcp ${VERSION}] ready - ${modeBanner}`);
     // Phase 19.8 - Supabase Realtime CDC subscription. Cloud mode only; legacy
     // snapshot mode has no live source to subscribe to.
-    if (creds) {
+    if (cloudGetClient) {
         const realtimeOn = await readRealtimeFlag();
         if (!realtimeOn) {
             console.error('[heuresis-mcp] realtime: disabled (--no-realtime or config).');
@@ -220,7 +262,7 @@ async function runServer() {
             // client (Supabase) is not reachable, the error surfaces on stderr.
             void (async () => {
                 try {
-                    const { client } = await getCloudClient(creds);
+                    const client = await cloudGetClient();
                     const wsId = await resolveSubscriptionWorkspaceId(client);
                     if (!wsId) {
                         console.error('[heuresis-mcp] realtime: no workspace visible; skipping subscription.');

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/dist/zod-to-json-schema.js

@@ -69,7 +69,32 @@ function leafSchema(schema) {
     return out;
 }
 export function zodToJsonSchema(schema) {
-    const shape = schema.shape;
+    // Peel wrappers to reach the underlying object whose `.shape` we can
+    // introspect: `.refine()`/`.transform()`/`.superRefine()` produce a
+    // ZodEffects (no `.shape`), and optional/default/nullable wrap the root too.
+    // Without this, a tool whose inputSchema is a ZodEffects (e.g. expand_concept)
+    // makes `Object.entries(undefined)` throw — which previously took down the
+    // ENTIRE tools/list response and caused MCP clients to drop the server.
+    let root = schema;
+    while (root && root._def) {
+        if (root instanceof z.ZodEffects) {
+            root = root._def.schema;
+            continue;
+        }
+        if (root instanceof z.ZodOptional ||
+            root instanceof z.ZodDefault ||
+            root instanceof z.ZodNullable) {
+            root = root._def.innerType;
+            continue;
+        }
+        break;
+    }
+    const shape = root?.shape;
+    if (!shape || typeof shape !== 'object') {
+        // Not an object schema we can introspect — expose a permissive object so
+        // the tool still lists and still accepts its arguments.
+        return { type: 'object', additionalProperties: true };
+    }
     const properties = {};
     const required = [];
     for (const [key, value] of Object.entries(shape)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heuresis/mcp",
-  "version": "1.0.0-rc.12",
+  "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",