@taskforcehq/taskforce 0.3.328 → 0.3.330

package/dist/mcp/localServiceProxy.js

@@ -1,17 +1,65 @@
 import { randomUUID } from 'crypto';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { JSONRPCMessageSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { JSONRPCMessageSchema } from '@modelcontextprotocol/core';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { normalizeMcpConnectionId, parseMcpClientId } from './clientRegistry.js';
 import { normalizeMcpToolProfile } from './toolProfiles.js';
+import { MCP_TOOL_REGISTRY, MCP_WRITE_TOOL_NAMES } from './toolRegistry.js';
 import { localServiceCloudTargetsEqual, parseLocalServiceCloudTarget, } from '../config/localServiceCloudTarget.js';
 import { discoverOrStartLocalService, LOCAL_SERVICE_API_BASE_PATH, LOCAL_SERVICE_PROTOCOL_VERSION, } from '../service/localServiceClientLifecycle.js';
 const REQUEST_TIMEOUT_MS = 120_000;
 const MAX_IN_FLIGHT = 32;
+const RECOVERY_FAILURE_COOLDOWN_MS = 250;
+const RECOVERY_TRANSITION_ATTEMPTS = 150;
+const RECOVERY_TRANSITION_POLL_MS = 100;
+const RECOVERY_TRANSITION_TIMEOUT_MS = 15_000;
 const MCP_PROTOCOL_ERROR = -32_000;
 const MCP_REQUEST_CANCELLED = -32_800;
+const KNOWN_READ_METHODS = new Set([
+    'initialize',
+    'ping',
+    'server/discover',
+    'tools/list',
+    'resources/list',
+    'resources/templates/list',
+    'resources/read',
+    'prompts/list',
+    'prompts/get',
+    'completion/complete',
+]);
+const RECOVERABLE_CONNECTION_CODES = new Set([
+    'GENERATION_MISMATCH',
+    'RUNTIME_CONTRACT_MISMATCH',
+    'SESSION_INVALID',
+    'SESSION_NOT_FOUND',
+    'SESSION_AUTH_REQUIRED',
+    'SERVICE_QUIESCING',
+]);
 function timeoutSignal(timeoutMs = REQUEST_TIMEOUT_MS) {
     return AbortSignal.timeout(timeoutMs);
 }
+function waitWithinRecoveryDeadline(operation, signal, deadlineAt) {
+    const remainingMs = deadlineAt - Date.now();
+    if (signal.aborted)
+        return Promise.reject(new Error('Taskforce MCP proxy recovery was stopped.'));
+    if (remainingMs <= 0)
+        return Promise.reject(new Error('Taskforce shared local service recovery timed out.'));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            callback();
+        };
+        const onAbort = () => finish(() => reject(new Error('Taskforce MCP proxy recovery was stopped.')));
+        const timer = setTimeout(() => finish(() => reject(new Error('Taskforce shared local service recovery timed out.'))), remainingMs);
+        timer.unref?.();
+        signal.addEventListener('abort', onAbort, { once: true });
+        operation.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}
 async function readJson(response, label) {
     const text = await response.text();
     if (!response.ok) {
@@ -24,6 +72,117 @@ async function readJson(response, label) {
         throw new Error(`${label} returned invalid JSON.`);
     }
 }
+function encodeMcpHeaderValue(value) {
+    const safeAscii = value.length > 0
+        && value === value.trim()
+        && !(value.startsWith('=?base64?') && value.endsWith('?='))
+        && [...value].every((character) => {
+            const codePoint = character.codePointAt(0) || 0;
+            return codePoint === 9 || (codePoint >= 32 && codePoint <= 126);
+        });
+    return safeAscii
+        ? value
+        : `=?base64?${Buffer.from(value, 'utf8').toString('base64')}?=`;
+}
+function modernRequestHeaders(message) {
+    if (!('method' in message) || !('id' in message))
+        return {};
+    const params = message.params;
+    const meta = params?._meta;
+    const version = meta?.['io.modelcontextprotocol/protocolVersion'];
+    if (typeof version !== 'string')
+        return {};
+    const name = message.method === 'resources/read'
+        ? params?.uri
+        : params?.name;
+    return {
+        'mcp-protocol-version': version,
+        'mcp-method': message.method,
+        ...(typeof name === 'string' ? { 'mcp-name': encodeMcpHeaderValue(name) } : {}),
+    };
+}
+function parseMcpRelayMessage(value) {
+    return JSONRPCMessageSchema.parse(value);
+}
+function parseSseFrame(frame) {
+    const data = frame
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith('data:'))
+        .map((line) => line.slice(5).trimStart())
+        .join('\n');
+    return data ? parseMcpRelayMessage(JSON.parse(data)) : null;
+}
+async function* readMcpRelayMessages(response) {
+    const contentType = String(response.headers.get('content-type') || '').toLowerCase();
+    if (!contentType.includes('text/event-stream')) {
+        const text = await response.text();
+        let values;
+        try {
+            const body = JSON.parse(text);
+            values = Array.isArray(body) ? body : [body];
+        }
+        catch {
+            if (!response.ok)
+                throw new Error(`MCP relay failed (${response.status}): ${text.slice(0, 500)}`);
+            throw new Error('MCP relay returned an invalid JSON-RPC response.');
+        }
+        if (values.length === 0)
+            throw new Error(`MCP relay returned no JSON-RPC messages (${response.status}).`);
+        for (const value of values)
+            yield parseMcpRelayMessage(value);
+        return;
+    }
+    if (!response.body)
+        throw new Error(`MCP relay returned no JSON-RPC messages (${response.status}).`);
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let sample = '';
+    let count = 0;
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (value) {
+                const decoded = decoder.decode(value, { stream: true });
+                buffer += decoded;
+                if (sample.length < 500)
+                    sample += decoded.slice(0, 500 - sample.length);
+            }
+            if (done)
+                buffer += decoder.decode();
+            let boundary = buffer.match(/\r?\n\r?\n/);
+            while (boundary?.index !== undefined) {
+                const frame = buffer.slice(0, boundary.index);
+                buffer = buffer.slice(boundary.index + boundary[0].length);
+                const message = parseSseFrame(frame);
+                if (message) {
+                    count += 1;
+                    yield message;
+                }
+                boundary = buffer.match(/\r?\n\r?\n/);
+            }
+            if (done)
+                break;
+        }
+        const finalMessage = parseSseFrame(buffer);
+        if (finalMessage) {
+            count += 1;
+            yield finalMessage;
+        }
+    }
+    catch {
+        if (!response.ok)
+            throw new Error(`MCP relay failed (${response.status}): ${sample.slice(0, 500)}`);
+        throw new Error('MCP relay returned an invalid JSON-RPC response.');
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+    if (count === 0) {
+        throw new Error(`MCP relay returned no JSON-RPC messages (${response.status}).`);
+    }
+}
 function validateReadiness(readiness, descriptor) {
     const readinessCloudTarget = parseLocalServiceCloudTarget(readiness.cloudTarget);
     if (!readiness.ready)
@@ -52,13 +211,96 @@ function cancellationTarget(message) {
 function idKey(id) {
     return `${typeof id}:${String(id)}`;
 }
-function errorResponse(id, message, code, numericCode = MCP_PROTOCOL_ERROR) {
+function errorResponse(id, message, code, numericCode = MCP_PROTOCOL_ERROR, data = {}) {
     return {
         jsonrpc: '2.0',
         id,
-        error: { code: numericCode, message, data: { code } },
+        error: { code: numericCode, message, data: { code, ...data } },
     };
 }
+function toolName(message) {
+    if (!('method' in message) || message.method !== 'tools/call')
+        return null;
+    const name = message.params?.name;
+    return typeof name === 'string' ? name : null;
+}
+function isKnownReadRequest(message) {
+    if (!('id' in message) || !('method' in message))
+        return false;
+    if (message.method === 'tools/call') {
+        const name = toolName(message);
+        return Boolean(name
+            && Object.prototype.hasOwnProperty.call(MCP_TOOL_REGISTRY, name)
+            && !MCP_WRITE_TOOL_NAMES.has(name));
+    }
+    return KNOWN_READ_METHODS.has(message.method);
+}
+function idempotencyKey(message) {
+    if (!('method' in message) || message.method !== 'tools/call')
+        return null;
+    const args = message.params?.arguments;
+    const value = args?.idempotencyKey ?? args?.operationKey;
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function requestProfileToken(message) {
+    if (!('method' in message) || message.method !== 'tools/call')
+        return null;
+    const args = message.params?.arguments;
+    const value = args?.profileToken;
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function responseProfileToken(message) {
+    if (!('result' in message) || !message.result || typeof message.result !== 'object')
+        return null;
+    const result = message.result;
+    if (result.isError === true)
+        return null;
+    const structuredToken = result.structuredContent?.profileToken;
+    if (typeof structuredToken === 'string' && structuredToken.trim())
+        return structuredToken.trim();
+    for (const item of result.content || []) {
+        if (item?.type !== 'text' || typeof item.text !== 'string')
+            continue;
+        try {
+            const parsed = JSON.parse(item.text);
+            if (typeof parsed?.profileToken === 'string' && parsed.profileToken.trim()) {
+                return parsed.profileToken.trim();
+            }
+        }
+        catch {
+            // Tool text is not generally JSON. Only resolve_profile's structured text is relevant here.
+        }
+    }
+    return null;
+}
+function isSuccessfulToolResponse(message) {
+    if (!('result' in message) || !message.result || typeof message.result !== 'object')
+        return false;
+    return message.result.isError !== true;
+}
+function descriptorsIdentifySameService(left, right) {
+    return left.generation === right.generation
+        && left.endpoint === right.endpoint
+        && left.protocolVersion === right.protocolVersion;
+}
+function isModernRequest(message) {
+    if (!('method' in message))
+        return false;
+    const meta = message.params?._meta;
+    return meta?.['io.modelcontextprotocol/protocolVersion'] === '2026-07-28';
+}
+async function recoverableResponseCode(response) {
+    if (![401, 409, 503].includes(response.status))
+        return null;
+    try {
+        const body = await response.clone().json();
+        const code = typeof body?.code === 'string' ? body.code : '';
+        return RECOVERABLE_CONNECTION_CODES.has(code) ? code : null;
+    }
+    catch {
+        return null;
+    }
+}
 export async function startLocalServiceMcpProxy(options) {
     const env = options.env || process.env;
     const configuredSharedService = String(env.TASKFORCE_SHARED_LOCAL_MCP_ENABLED || '').trim();
@@ -91,51 +333,164 @@ export async function startLocalServiceMcpProxy(options) {
     if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs < 1)
         throw new Error('Local MCP proxy requestTimeoutMs must be positive.');
     const fetchFn = options.fetch || fetch;
-    const descriptor = await (options.discover || discoverOrStartLocalService)({
+    const discover = options.discover || discoverOrStartLocalService;
+    const sleep = options.sleep || ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+    let privateProfileToken = String(env.TASKFORCE_AI_PROFILE_TOKEN || '').trim() || undefined;
+    const discoverDescriptor = () => discover({
         projectRoot: options.projectRoot,
         env,
         executablePath: options.executablePath,
         cliEntryPath: options.cliEntryPath,
         execArgv: options.execArgv,
     });
-    const readiness = await readJson(await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/readiness`, { signal: timeoutSignal() }), 'Local service readiness');
-    validateReadiness(readiness, descriptor);
-    const registration = await readJson(await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/sessions`, {
-        method: 'POST',
-        headers: {
-            'content-type': 'application/json',
-            'x-taskforce-local-service-capability': descriptor.bootstrapCapability,
-        },
-        body: JSON.stringify({
-            clientId,
-            connectionInstance,
-            workspaceId,
-            permissions: ['tasks:read', 'tasks:write', 'workspace:read'],
-            toolProfile,
-            protocolVersion: descriptor.protocolVersion,
-            generation: descriptor.generation,
-            profileToken: String(env.TASKFORCE_AI_PROFILE_TOKEN || '').trim() || undefined,
-        }),
-        signal: timeoutSignal(),
-    }), 'Local service session registration');
-    if (!registration.session?.id || !registration.bearerToken) {
-        throw new Error('Local service session registration returned an invalid response.');
-    }
+    const registerConnection = async (descriptor, recoverySignal) => {
+        const registrationSignal = recoverySignal
+            ? AbortSignal.any([recoverySignal, timeoutSignal()])
+            : timeoutSignal();
+        const readiness = await readJson(await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/readiness`, { signal: registrationSignal }), 'Local service readiness');
+        validateReadiness(readiness, descriptor);
+        const registration = await readJson(await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/sessions`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-taskforce-local-service-capability': descriptor.bootstrapCapability,
+            },
+            body: JSON.stringify({
+                clientId,
+                connectionInstance,
+                workspaceId,
+                permissions: ['tasks:read', 'tasks:write', 'workspace:read'],
+                toolProfile,
+                protocolVersion: descriptor.protocolVersion,
+                generation: descriptor.generation,
+                profileToken: privateProfileToken,
+            }),
+            signal: registrationSignal,
+        }), 'Local service session registration');
+        if (!registration.session?.id || !registration.bearerToken) {
+            throw new Error('Local service session registration returned an invalid response.');
+        }
+        return { descriptor, registration };
+    };
+    const establishConnection = async () => (registerConnection(await discoverDescriptor()));
+    let connection = await establishConnection();
+    let terminal = false;
+    let recoveryState = null;
+    let lastRecoveryFailure = null;
+    let closing = false;
+    const recoveryIntentFor = (recoveryCode) => {
+        if (recoveryCode === null)
+            return 'probe';
+        if (recoveryCode === 'SESSION_INVALID' || recoveryCode === 'SESSION_NOT_FOUND') {
+            return 'register-current';
+        }
+        return 'replacement';
+    };
+    const raiseRecoveryIntent = (current, requested) => {
+        const priority = { probe: 0, 'register-current': 1, replacement: 2 };
+        return priority[requested] > priority[current] ? requested : current;
+    };
+    const recoverConnection = (failedConnection, recoveryCode) => {
+        if (closing || terminal)
+            return Promise.reject(new Error('Taskforce MCP proxy is closed.'));
+        if (connection !== failedConnection)
+            return Promise.resolve(connection);
+        const requestedIntent = recoveryIntentFor(recoveryCode);
+        if (recoveryState) {
+            recoveryState.intent = raiseRecoveryIntent(recoveryState.intent, requestedIntent);
+            return recoveryState.promise.then((replacement) => {
+                if (requestedIntent !== 'probe'
+                    && descriptorsIdentifySameService(replacement.descriptor, failedConnection.descriptor)) {
+                    return recoverConnection(failedConnection, recoveryCode);
+                }
+                return replacement;
+            });
+        }
+        if (lastRecoveryFailure?.connection === failedConnection
+            && Date.now() - lastRecoveryFailure.at < RECOVERY_FAILURE_COOLDOWN_MS) {
+            return Promise.reject(lastRecoveryFailure.error);
+        }
+        const state = {
+            controller: new AbortController(),
+            intent: requestedIntent,
+            promise: Promise.resolve(failedConnection),
+        };
+        recoveryState = state;
+        const deadlineAt = Date.now() + Math.min(requestTimeoutMs, RECOVERY_TRANSITION_TIMEOUT_MS);
+        const recoveryDeadlineTimer = setTimeout(() => state.controller.abort(), Math.max(1, deadlineAt - Date.now()));
+        recoveryDeadlineTimer.unref?.();
+        state.promise = (async () => {
+            let lastError = null;
+            for (let attempt = 0; attempt < RECOVERY_TRANSITION_ATTEMPTS; attempt += 1) {
+                if (closing || terminal || state.controller.signal.aborted) {
+                    throw new Error('Taskforce MCP proxy is closed.');
+                }
+                let candidate;
+                try {
+                    candidate = await waitWithinRecoveryDeadline(discoverDescriptor(), state.controller.signal, deadlineAt);
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                    if (Date.now() >= deadlineAt || state.controller.signal.aborted)
+                        throw lastError;
+                    if (attempt + 1 < RECOVERY_TRANSITION_ATTEMPTS) {
+                        await waitWithinRecoveryDeadline(sleep(RECOVERY_TRANSITION_POLL_MS), state.controller.signal, deadlineAt);
+                    }
+                    continue;
+                }
+                if (!descriptorsIdentifySameService(candidate, failedConnection.descriptor)) {
+                    return await waitWithinRecoveryDeadline(registerConnection(candidate, state.controller.signal), state.controller.signal, deadlineAt);
+                }
+                if (state.intent === 'probe')
+                    return failedConnection;
+                if (state.intent === 'register-current') {
+                    return await waitWithinRecoveryDeadline(registerConnection(candidate, state.controller.signal), state.controller.signal, deadlineAt);
+                }
+                if (attempt + 1 < RECOVERY_TRANSITION_ATTEMPTS) {
+                    await waitWithinRecoveryDeadline(sleep(RECOVERY_TRANSITION_POLL_MS), state.controller.signal, deadlineAt);
+                }
+            }
+            throw lastError || new Error('Taskforce shared local service replacement did not become ready.');
+        })()
+            .then((replacement) => {
+            connection = replacement;
+            lastRecoveryFailure = null;
+            return replacement;
+        })
+            .catch((error) => {
+            const normalized = error instanceof Error ? error : new Error(String(error));
+            lastRecoveryFailure = { connection: failedConnection, error: normalized, at: Date.now() };
+            throw normalized;
+        })
+            .finally(() => {
+            clearTimeout(recoveryDeadlineTimer);
+            if (recoveryState === state)
+                recoveryState = null;
+        });
+        return state.promise;
+    };
     const stdio = new StdioServerTransport(options.stdin, options.stdout);
     const requests = new Map();
     const inFlight = new Set();
     let protocolVersion = null;
     let initializeRequestId = null;
-    let terminal = false;
     let closePromise = null;
     let sendChain = Promise.resolve();
     const send = (message) => {
         sendChain = sendChain.then(() => stdio.send(message));
         return sendChain;
     };
+    const revokeConnection = async (target) => {
+        await fetchFn(`${target.descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/sessions/${encodeURIComponent(target.registration.session.id)}`, {
+            method: 'DELETE',
+            headers: { authorization: `Bearer ${target.registration.bearerToken}` },
+            signal: timeoutSignal(2_000),
+        }).then((response) => response.body?.cancel()).catch(() => undefined);
+    };
     const failTerminal = async (error, id) => {
         if (terminal)
             return;
+        const pendingRecovery = recoveryState?.promise || null;
         terminal = true;
         for (const pending of inFlight)
             pending.controller.abort();
@@ -145,8 +500,58 @@ export async function startLocalServiceMcpProxy(options) {
         else {
             (options.logError || console.error)(`[Taskforce MCP proxy] ${error.message}`);
         }
+        await pendingRecovery?.catch(() => undefined);
+        await revokeConnection(connection);
         options.onFatal?.(error);
     };
+    const relayOnce = async (message, target, state, cancelCorrelation) => {
+        const response = await fetchFn(`${target.descriptor.endpoint}/mcp`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${target.registration.bearerToken}`,
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+                ...(protocolVersion ? { 'mcp-protocol-version': protocolVersion } : {}),
+                ...modernRequestHeaders(message),
+                'x-taskforce-mcp-request-correlation': state.correlationId,
+                ...(cancelCorrelation ? { 'x-taskforce-mcp-cancel-correlation': cancelCorrelation } : {}),
+            },
+            body: JSON.stringify(message),
+            signal: state.controller.signal,
+        });
+        const recoveryCode = await recoverableResponseCode(response);
+        if (recoveryCode) {
+            await response.body?.cancel();
+            return recoveryCode;
+        }
+        if (response.status === 202) {
+            await response.body?.cancel();
+            return null;
+        }
+        for await (const responseMessage of readMcpRelayMessages(response)) {
+            if (initializeRequestId !== null
+                && requestId(responseMessage) === initializeRequestId
+                && 'result' in responseMessage
+                && typeof responseMessage.result?.protocolVersion === 'string') {
+                protocolVersion = responseMessage.result.protocolVersion;
+            }
+            if (requestId(responseMessage) === requestId(message)) {
+                state.responseDelivered = true;
+                if (isSuccessfulToolResponse(responseMessage)) {
+                    const suppliedProfileToken = requestProfileToken(message);
+                    if (toolName(message) === 'resolve_profile') {
+                        privateProfileToken = responseProfileToken(responseMessage)
+                            || suppliedProfileToken
+                            || privateProfileToken;
+                    }
+                    else if (suppliedProfileToken)
+                        privateProfileToken = suppliedProfileToken;
+                }
+            }
+            await send(responseMessage);
+        }
+        return null;
+    };
     const forward = async (message) => {
         const id = requestId(message);
         if (terminal) {
@@ -173,7 +578,7 @@ export async function startLocalServiceMcpProxy(options) {
         }
         const controller = new AbortController();
         const key = id === null ? null : idKey(id);
-        const state = { controller, cancelled: false, correlationId: randomUUID() };
+        const state = { controller, cancelled: false, correlationId: randomUUID(), responseDelivered: false };
         const requestTimer = setTimeout(() => controller.abort(), requestTimeoutMs);
         requestTimer.unref?.();
         inFlight.add(state);
@@ -181,41 +586,94 @@ export async function startLocalServiceMcpProxy(options) {
             requests.set(key, state);
         if ('method' in message && message.method === 'initialize' && id !== null)
             initializeRequestId = id;
+        let attemptedConnection = connection;
+        let retried = false;
+        let definitivelyRejected = false;
         try {
-            const response = await fetchFn(`${descriptor.endpoint}/mcp`, {
-                method: 'POST',
-                headers: {
-                    authorization: `Bearer ${registration.bearerToken}`,
-                    'content-type': 'application/json',
-                    accept: 'application/json, text/event-stream',
-                    ...(protocolVersion ? { 'mcp-protocol-version': protocolVersion } : {}),
-                    'x-taskforce-mcp-request-correlation': state.correlationId,
-                    ...(cancelCorrelation ? { 'x-taskforce-mcp-cancel-correlation': cancelCorrelation } : {}),
-                },
-                body: JSON.stringify(message),
-                signal: controller.signal,
-            });
-            if (response.status === 202) {
-                await response.body?.cancel();
-                return;
-            }
-            const body = await readJson(response, 'MCP relay');
-            const messages = (Array.isArray(body) ? body : [body]).map((value) => JSONRPCMessageSchema.parse(value));
-            for (const responseMessage of messages) {
-                if (initializeRequestId !== null
-                    && requestId(responseMessage) === initializeRequestId
-                    && 'result' in responseMessage
-                    && typeof responseMessage.result?.protocolVersion === 'string') {
-                    protocolVersion = responseMessage.result.protocolVersion;
+            const recoveryCode = await relayOnce(message, attemptedConnection, state, cancelCorrelation);
+            if (recoveryCode) {
+                definitivelyRejected = true;
+                attemptedConnection = await recoverConnection(attemptedConnection, recoveryCode);
+                retried = true;
+                const repeatedRecoveryCode = await relayOnce(message, attemptedConnection, state, cancelCorrelation);
+                if (repeatedRecoveryCode) {
+                    throw new Error(`Replacement local service rejected the credential (${repeatedRecoveryCode}).`);
                 }
-                await send(responseMessage);
             }
         }
         catch (error) {
+            if (closing)
+                return;
+            if (terminal)
+                return;
+            if (state.responseDelivered) {
+                (options.logError || console.error)(`[Taskforce MCP proxy] Relay failed after delivering the response: ${String(error?.message || error)}`);
+                return;
+            }
             if (state.cancelled && id !== null) {
                 await send(errorResponse(id, 'Client stopped waiting; the operation may still complete.', 'REQUEST_CANCELLED_ADVISORY', MCP_REQUEST_CANCELLED));
                 return;
             }
+            if (definitivelyRejected && !retried) {
+                await failTerminal(error instanceof Error ? error : new Error(String(error)), id);
+                return;
+            }
+            if (id !== null && isKnownReadRequest(message) && !retried && !state.controller.signal.aborted) {
+                try {
+                    attemptedConnection = await recoverConnection(attemptedConnection, null);
+                    retried = true;
+                    const recoveryCode = await relayOnce(message, attemptedConnection, state, cancelCorrelation);
+                    if (recoveryCode) {
+                        throw new Error(`Replacement local service rejected the credential (${recoveryCode}).`);
+                    }
+                    return;
+                }
+                catch (retryError) {
+                    await failTerminal(retryError instanceof Error ? retryError : new Error(String(retryError)), id);
+                    return;
+                }
+            }
+            if (id !== null && !isKnownReadRequest(message)) {
+                await recoverConnection(attemptedConnection, null).catch((recoveryError) => {
+                    (options.logError || console.error)(`[Taskforce MCP proxy] Recovery after an outcome-uncertain request failed: ${String(recoveryError?.message || recoveryError)}`);
+                });
+                if (closing)
+                    return;
+                const operationKey = idempotencyKey(message);
+                const guidance = operationKey
+                    ? 'Taskforce could not confirm whether the operation completed. Do not retry automatically. Preserve the idempotency key, verify the intended state with the relevant Taskforce read or search tool, and retry only after confirming the operation is absent.'
+                    : 'Taskforce could not confirm whether the operation completed. Do not retry automatically. Verify the intended state with the relevant Taskforce read or search tool before deciding whether any manual retry is safe.';
+                const outcome = {
+                    code: 'LOCAL_SERVICE_OUTCOME_UNCERTAIN',
+                    outcomeUncertain: true,
+                    retryable: false,
+                    ...(operationKey ? { idempotencyKey: operationKey } : {}),
+                    operationId: null,
+                    operationLookup: {
+                        endpointTemplate: `${connection.descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/operations/{operationId}`,
+                        status: 'operation_id_required',
+                        requiresPrivateProxyCredential: true,
+                    },
+                    verificationGuidance: 'Use the relevant Taskforce read or search tool with the original target and payload. The idempotency key is not the canonical operation ID.',
+                };
+                if (!('method' in message) || message.method !== 'tools/call') {
+                    await send(errorResponse(id, guidance, 'LOCAL_SERVICE_OUTCOME_UNCERTAIN', MCP_PROTOCOL_ERROR, outcome));
+                    return;
+                }
+                await send({
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        content: [{ type: 'text', text: guidance }],
+                        structuredContent: outcome,
+                        isError: true,
+                        ...(isModernRequest(message)
+                            ? { resultType: 'complete' }
+                            : {}),
+                    },
+                });
+                return;
+            }
             await failTerminal(error instanceof Error ? error : new Error(String(error)), id);
         }
         finally {
@@ -225,34 +683,38 @@ export async function startLocalServiceMcpProxy(options) {
                 requests.delete(key);
         }
     };
-    stdio.onmessage = (message) => { void forward(message); };
+    const forwardPromises = new Set();
+    stdio.onmessage = (message) => {
+        const pending = forward(message).finally(() => { forwardPromises.delete(pending); });
+        forwardPromises.add(pending);
+    };
     stdio.onerror = (error) => { void failTerminal(error, null); };
     try {
         await stdio.start();
     }
     catch (error) {
-        await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/sessions/${encodeURIComponent(registration.session.id)}`, {
-            method: 'DELETE',
-            headers: { authorization: `Bearer ${registration.bearerToken}` },
-            signal: timeoutSignal(2_000),
-        }).then((response) => response.body?.cancel()).catch(() => undefined);
+        await revokeConnection(connection);
         throw error;
     }
     const close = () => {
         if (closePromise)
             return closePromise;
+        closing = true;
         terminal = true;
+        const pendingRecovery = recoveryState?.promise || null;
         closePromise = (async () => {
             for (const pending of inFlight)
                 pending.controller.abort();
             await stdio.close().catch(() => undefined);
-            await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/sessions/${encodeURIComponent(registration.session.id)}`, {
-                method: 'DELETE',
-                headers: { authorization: `Bearer ${registration.bearerToken}` },
-                signal: timeoutSignal(2_000),
-            }).then((response) => response.body?.cancel()).catch(() => undefined);
+            await Promise.allSettled([...forwardPromises]);
+            await pendingRecovery?.catch(() => undefined);
+            const activeConnection = connection;
+            await revokeConnection(activeConnection);
         })();
         return closePromise;
     };
-    return { close, sessionId: registration.session.id };
+    return {
+        close,
+        get sessionId() { return connection.registration.session.id; },
+    };
 }