@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/mcp/durableTaskRootMutationRouter.js

@@ -0,0 +1,226 @@
+import { randomUUID } from 'crypto';
+import { validateDurableTaskCreateInput } from '../core/TaskDurableCreateMutationService.js';
+import { validateDurableTaskMetadataPatch } from '../core/TaskDurableSyncMutationService.js';
+import { enqueueLocalTaskCreateMutation } from '../sync/v3/localTaskCreateOutboxService.js';
+import { enqueueLocalTaskMetadataMutation } from '../sync/v3/localTaskMetadataOutboxService.js';
+import { LocalSyncIdentityStore } from '../sync/v3/localSyncIdentityStore.js';
+import { WorkspaceSyncDurabilityStore } from '../sync/v3/syncDurabilityStore.js';
+import { runDurableTaskCreate } from '../sync/v3/taskCreateMutationService.js';
+import { runDurableTaskMetadataUpdate } from '../sync/v3/taskMetadataMutationService.js';
+import { DurableOperationReplayIdentityConflictError, readDurableOperationReplay, } from '../sync/v3/durableOperationReplay.js';
+const OPERATION_LEASE_MS = 30_000;
+function isEnabled(value) {
+    return /^(1|true|on|yes)$/i.test(String(value || '').trim());
+}
+export function resolveMcpTaskRootActivationCapability(input) {
+    const env = input.env || process.env;
+    const cloudAcceptance = isEnabled(env.TASKFORCE_SYNC_V3_TASKS_ENABLED);
+    const localPipeline = input.runtimeMode === 'cloud' || (isEnabled(env.TASKFORCE_SYNC_V3_LOCAL_CAPTURE_ENABLED)
+        && isEnabled(env.TASKFORCE_SYNC_V3_LOCAL_DISPATCH_ENABLED));
+    const createSurfaceKey = 'TASKFORCE_SYNC_V3_TASK_CREATE_MCP_ACTIVATION_ENABLED';
+    const metadataSurfaceKey = 'TASKFORCE_SYNC_V3_TASK_METADATA_MCP_ACTIVATION_ENABLED';
+    const persistedCreateOwnership = input.runtimeMode === 'local'
+        && !Object.prototype.hasOwnProperty.call(env, createSurfaceKey)
+        && input.readPersistedProjectionOwner?.() === 'v3';
+    const persistedMetadataOwnership = input.runtimeMode === 'local'
+        && !Object.prototype.hasOwnProperty.call(env, metadataSurfaceKey)
+        && input.readPersistedProjectionOwner?.() === 'v3';
+    return {
+        taskCreateMcpActivation: persistedCreateOwnership || (cloudAcceptance
+            && isEnabled(env.TASKFORCE_SYNC_V3_TASK_CREATE_MCP_ACTIVATION_ENABLED)
+            && (input.runtimeMode === 'cloud' || (localPipeline && isEnabled(env.TASKFORCE_SYNC_V3_TASK_CREATE_CAPTURE_ENABLED)))),
+        taskMetadataMcpActivation: persistedMetadataOwnership || (cloudAcceptance
+            && isEnabled(env.TASKFORCE_SYNC_V3_TASK_METADATA_MCP_ACTIVATION_ENABLED)
+            && localPipeline),
+    };
+}
+export class DurableTaskRootMutationRouterDisabledError extends Error {
+    code = 'WORKSPACE_SYNC_V3_TASK_ROOT_MCP_DISABLED';
+    constructor() {
+        super('Durable MCP task-root activation is disabled.');
+        this.name = 'DurableTaskRootMutationRouterDisabledError';
+    }
+}
+export class DurableTaskRootMutationRouterInProgressError extends Error {
+    retryAt;
+    code = 'WORKSPACE_SYNC_OPERATION_IN_PROGRESS';
+    constructor(retryAt) {
+        super('The durable MCP task-root mutation is already in progress.');
+        this.retryAt = retryAt;
+        this.name = 'DurableTaskRootMutationRouterInProgressError';
+    }
+}
+function requiredText(value, label) {
+    const text = String(value || '').trim();
+    if (!text)
+        throw new Error(`${label} is required.`);
+    return text;
+}
+export function createDurableTaskRootMutationRouter(input) {
+    const tenantId = requiredText(input.tenantId, 'Tenant id');
+    const workspaceId = requiredText(input.workspaceId, 'Workspace id');
+    const store = new WorkspaceSyncDurabilityStore(input.core.getDatabaseAdapter());
+    const resolveCapability = () => {
+        let persistedCreateOwnershipChecked = false;
+        let persistedMetadataOwnershipChecked = false;
+        const capability = resolveMcpTaskRootActivationCapability({
+            ...input,
+            readPersistedProjectionOwner: () => {
+                const env = input.env || process.env;
+                if (!Object.prototype.hasOwnProperty.call(env, 'TASKFORCE_SYNC_V3_TASK_CREATE_MCP_ACTIVATION_ENABLED')) {
+                    persistedCreateOwnershipChecked = true;
+                }
+                if (!Object.prototype.hasOwnProperty.call(env, 'TASKFORCE_SYNC_V3_TASK_METADATA_MCP_ACTIVATION_ENABLED')) {
+                    persistedMetadataOwnershipChecked = true;
+                }
+                return store.readCombinedProjectionOwnership({ tenantId, workspaceId }).owner;
+            },
+        });
+        return { capability, persistedCreateOwnershipChecked, persistedMetadataOwnershipChecked };
+    };
+    const identityStore = new LocalSyncIdentityStore(input.core.getDatabaseAdapter());
+    const createOperationId = input.createOperationId || (() => `operation-${randomUUID()}`);
+    const now = input.now || (() => new Date());
+    const operationContext = (enabled, mutationKind, taskId, options) => {
+        if (!enabled)
+            throw new DurableTaskRootMutationRouterDisabledError();
+        const acceptedAt = now();
+        const acceptedAtIso = acceptedAt.toISOString();
+        const baseOperationId = requiredText(createOperationId({
+            mutationKind,
+            taskId,
+            operationKey: options?.operationKey,
+        }), 'Operation id');
+        const operationId = baseOperationId;
+        const clientId = input.runtimeMode === 'local'
+            ? identityStore.getOrCreateClientId(acceptedAtIso)
+            : requiredText(input.cloudClientId || 'mcp-cloud', 'Cloud client id');
+        return { acceptedAt, acceptedAtIso, operationId, identity: { tenantId, workspaceId, clientId, operationId } };
+    };
+    const canonicalTask = (taskId) => {
+        const task = input.core.getTask(taskId, workspaceId);
+        if (!task)
+            throw new Error(`Task ${taskId} not found after durable mutation.`);
+        return task;
+    };
+    return {
+        get createEnabled() { return resolveCapability().capability.taskCreateMcpActivation; },
+        get metadataEnabled() { return resolveCapability().capability.taskMetadataMcpActivation; },
+        create(args) {
+            const taskId = requiredText(args.taskId, 'Task id');
+            const actorRef = requiredText(args.actorRef, 'Actor ref');
+            const operationKey = args.operationKey === undefined
+                ? undefined
+                : requiredText(args.operationKey, 'Operation key');
+            if (operationKey && operationKey.length > 128) {
+                throw new Error('Operation key must contain at most 128 characters.');
+            }
+            const task = validateDurableTaskCreateInput(args.task);
+            const createCapability = resolveCapability();
+            const context = operationContext(createCapability.capability.taskCreateMcpActivation, 'create', taskId, {
+                operationKey,
+            });
+            if (input.runtimeMode === 'local') {
+                const result = enqueueLocalTaskCreateMutation({ store, core: input.core, identity: context.identity,
+                    taskId, task, now: context.acceptedAtIso, actorRef,
+                    requireV3CombinedOwnership: createCapability.persistedCreateOwnershipChecked,
+                    onPostCommitError: input.onPostCommitError });
+                return { state: 'pending', route: 'local-outbox', operationId: context.operationId,
+                    replayed: !result.enqueued,
+                    task: result.task || canonicalTask(taskId) };
+            }
+            const result = runDurableTaskCreate({ store, core: input.core, tenantId, workspaceId,
+                clientId: context.identity.clientId, operationId: context.operationId, provisionalTaskId: taskId,
+                task, baseEntityRevision: 0, baseLifecycleRevision: 0, now: context.acceptedAtIso,
+                leaseExpiresAt: new Date(context.acceptedAt.getTime() + OPERATION_LEASE_MS).toISOString(),
+                actorRef, onPostCommitError: input.onPostCommitError });
+            if (result.state === 'in_progress')
+                throw new DurableTaskRootMutationRouterInProgressError(result.retryAt);
+            return { state: 'committed', route: 'cloud-acceptance', operationId: context.operationId,
+                replayed: result.replayed,
+                task: result.response.authoritative.payload };
+        },
+        updateMetadata(args) {
+            const taskId = requiredText(args.taskId, 'Task id');
+            const actorRef = requiredText(args.actorRef, 'Actor ref');
+            const patch = validateDurableTaskMetadataPatch(args.patch);
+            const metadataCapability = resolveCapability();
+            const context = operationContext(metadataCapability.capability.taskMetadataMcpActivation, 'metadata-update', taskId, {
+                operationKey: args.operationKey,
+            });
+            if (input.runtimeMode === 'local') {
+                const result = enqueueLocalTaskMetadataMutation({ store, core: input.core, identity: context.identity,
+                    taskId, patch, now: context.acceptedAtIso, actorRef,
+                    requireV3CombinedOwnership: metadataCapability.persistedMetadataOwnershipChecked,
+                    onPostCommitError: input.onPostCommitError });
+                return { state: 'pending', route: 'local-outbox', operationId: context.operationId,
+                    replayed: !result.enqueued,
+                    task: result.task || canonicalTask(taskId) };
+            }
+            let baseEntityRevision;
+            let baseLifecycleRevision;
+            const committedResponseJson = store.readCommittedOperationResponse(context.identity);
+            if (committedResponseJson) {
+                try {
+                    const replay = readDurableOperationReplay({
+                        responseJson: committedResponseJson,
+                        operationId: context.operationId,
+                        domain: 'task',
+                        entityId: taskId,
+                        mutationKind: 'metadata-update',
+                        revisionMode: 'metadata',
+                        requirePayload: true,
+                    });
+                    baseEntityRevision = replay.baseEntityRevision;
+                    baseLifecycleRevision = replay.baseLifecycleRevision;
+                }
+                catch (error) {
+                    if (error instanceof DurableOperationReplayIdentityConflictError) {
+                        throw new Error('Operation identity is already assigned to another task mutation.');
+                    }
+                    throw new Error('Committed durable MCP task metadata response is invalid.');
+                }
+            }
+            else {
+                const revisions = store.readEntityRevisionCoordinates({
+                    tenantId,
+                    workspaceId,
+                    domain: 'task',
+                    entityId: taskId,
+                });
+                baseEntityRevision = revisions.entityRevision;
+                baseLifecycleRevision = revisions.lifecycleRevision;
+            }
+            const result = runDurableTaskMetadataUpdate({ store, core: input.core, tenantId, workspaceId,
+                clientId: context.identity.clientId, operationId: context.operationId, taskId, patch,
+                baseEntityRevision, baseLifecycleRevision,
+                now: context.acceptedAtIso,
+                leaseExpiresAt: new Date(context.acceptedAt.getTime() + OPERATION_LEASE_MS).toISOString(),
+                actorRef, onPostCommitError: input.onPostCommitError });
+            if (result.state === 'in_progress')
+                throw new DurableTaskRootMutationRouterInProgressError(result.retryAt);
+            if (result.replayed) {
+                try {
+                    readDurableOperationReplay({
+                        responseJson: result.responseJson,
+                        operationId: context.operationId,
+                        domain: 'task',
+                        entityId: taskId,
+                        mutationKind: 'metadata-update',
+                        revisionMode: 'metadata',
+                        requirePayload: true,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof DurableOperationReplayIdentityConflictError) {
+                        throw new Error('Operation identity is already assigned to another durable MCP task mutation.');
+                    }
+                    throw new Error('Committed durable MCP task metadata response is invalid.');
+                }
+            }
+            return { state: 'committed', route: 'cloud-acceptance', operationId: context.operationId,
+                replayed: result.replayed,
+                task: result.response.authoritative.payload };
+        },
+    };
+}

package/dist/mcp/gitWorktreeRoots.d.ts

@@ -0,0 +1,2 @@
+export declare function parseGitWorktreeRoots(output: string): string[];
+export declare function listRegisteredGitWorktreeRoots(projectRoot: string): string[];

package/dist/mcp/gitWorktreeRoots.js

@@ -0,0 +1,19 @@
+import { execFileSync } from 'node:child_process';
+export function parseGitWorktreeRoots(output) {
+    return String(output || '')
+        .split('\0\0')
+        .map((record) => record.split('\0'))
+        .filter((fields) => !fields.some((field) => field === 'bare' || field.startsWith('prunable')))
+        .map((fields) => fields.find((field) => field.startsWith('worktree '))?.slice('worktree '.length) || '')
+        .filter(Boolean);
+}
+export function listRegisteredGitWorktreeRoots(projectRoot) {
+    try {
+        const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+        const output = execFileSync('git', ['-C', projectRoot, 'worktree', 'list', '--porcelain', '-z'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000, maxBuffer: 1024 * 1024, env });
+        return parseGitWorktreeRoots(output);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/mcp/legacyServer.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp/legacyServer.js

@@ -0,0 +1,42 @@
+import { readFileSync } from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { startTaskforceMcpStdioServer } from './runtime.js';
+import { observeTaskforceMcpStdioShutdown } from './stdioLifecycle.js';
+import { acquireLocalServiceOwnershipForRuntime } from '../server/localServiceOwnershipBootstrap.js';
+const projectRoot = process.argv[2] || process.cwd();
+const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+const runtimeVersion = String(JSON.parse(readFileSync(packagePath, 'utf8')).version || '').trim();
+const rollbackVersion = String(process.env.TASKFORCE_SHARED_LOCAL_MCP_ROLLBACK_VERSION || '').trim();
+if (process.env.TASKFORCE_SHARED_LOCAL_MCP_CLIENT_MODE !== 'legacy'
+    || process.env.TASKFORCE_SHARED_LOCAL_MCP_ENABLED !== 'false'
+    || !runtimeVersion
+    || rollbackVersion !== runtimeVersion) {
+    throw new Error('Legacy MCP is available only for an explicit stopped-service rollback whose requested version exactly matches this runtime.');
+}
+const ownership = await acquireLocalServiceOwnershipForRuntime(projectRoot, process.env);
+if (!ownership?.owned) {
+    throw new Error('Legacy MCP rollback could not acquire exclusive local data ownership. '
+        + 'Quiesce MCP clients and stop the shared service before retrying.');
+}
+let runtime = null;
+try {
+    runtime = await startTaskforceMcpStdioServer({
+        projectRoot,
+        localDataOwnerPermit: ownership.localDataOwnerPermit || undefined,
+    });
+    const lifecycle = observeTaskforceMcpStdioShutdown({
+        stdin: process.stdin,
+        process,
+        close: runtime.close,
+    });
+    await lifecycle.closed;
+}
+finally {
+    try {
+        await runtime?.close();
+    }
+    finally {
+        await ownership.release();
+    }
+}

package/dist/mcp/localCliHealth.d.ts

@@ -0,0 +1,56 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+export type LocalCliHealthState = 'healthy' | 'version-mismatch' | 'unusable';
+export interface LocalCliHealthResult {
+    state: LocalCliHealthState;
+    code: string;
+    message: string;
+    executablePath: string | null;
+    cliVersion: string | null;
+    appVersion: string;
+    serverName: string | null;
+    toolCount: number | null;
+}
+interface ProbeInput {
+    projectRoot: string;
+    tenantId: string;
+    workspaceId: string;
+    appVersion: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}
+interface ProbeDependencies {
+    resolveExecutable?: (command: string, env: NodeJS.ProcessEnv) => string | null;
+    readVersion?: (executablePath: string, timeoutMs: number) => Promise<string>;
+    handshake?: (input: {
+        executablePath: string;
+        projectRoot: string;
+        tenantId: string;
+        workspaceId: string;
+        timeoutMs: number;
+    }) => Promise<{
+        serverName: string | null;
+        toolNames: string[];
+    }>;
+}
+export declare function resolveExecutableOnPath(command: string, env?: NodeJS.ProcessEnv): string | null;
+export declare function getTaskforceRuntimeVersion(): string;
+export declare function resolveCliLaunch(executablePath: string, platform?: NodeJS.Platform, fileExists?: (candidate: string) => boolean): {
+    command: string;
+    argsPrefix: string[];
+};
+export declare function performMcpHandshake(input: {
+    executablePath: string;
+    projectRoot: string;
+    tenantId: string;
+    workspaceId: string;
+    timeoutMs: number;
+}, dependencies?: {
+    createTransport?: (parameters: ConstructorParameters<typeof StdioClientTransport>[0]) => StdioClientTransport;
+    createClient?: () => Client;
+}): Promise<{
+    serverName: string | null;
+    toolNames: string[];
+}>;
+export declare function probeGlobalTaskforceCli(input: ProbeInput, dependencies?: ProbeDependencies): Promise<LocalCliHealthResult>;
+export {};

package/dist/mcp/localCliHealth.js

@@ -0,0 +1,170 @@
+import { execFile } from 'node:child_process';
+import { constants as fsConstants, accessSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { getDefaultEnvironment, StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+const execFileAsync = promisify(execFile);
+const DEFAULT_TIMEOUT_MS = 5_000;
+function stripAnsi(value) {
+    return value.replace(/\u001b\[[0-9;]*m/g, '');
+}
+function normalizeVersion(value) {
+    const normalized = stripAnsi(String(value || '')).trim();
+    const match = normalized.match(/^(?:Taskforce CLI v)?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?:\+[0-9A-Za-z.-]+)?$/);
+    return match?.[1] || null;
+}
+function comparableVersion(value) {
+    return normalizeVersion(String(value || '').replace(/^v/, ''));
+}
+export function resolveExecutableOnPath(command, env = process.env) {
+    const pathValue = String(env.PATH || '').trim();
+    if (!pathValue)
+        return null;
+    const extensions = process.platform === 'win32'
+        ? String(env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean)
+        : [''];
+    for (const directory of pathValue.split(path.delimiter).filter(Boolean)) {
+        for (const extension of extensions) {
+            const candidate = path.join(directory, `${command}${extension}`);
+            try {
+                accessSync(candidate, fsConstants.X_OK);
+                if (!statSync(candidate).isFile())
+                    continue;
+                return path.resolve(candidate);
+            }
+            catch {
+                // Continue through PATH candidates.
+            }
+        }
+    }
+    return null;
+}
+export function getTaskforceRuntimeVersion() {
+    try {
+        const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+        const parsed = JSON.parse(readFileSync(packagePath, 'utf8'));
+        return String(parsed.version || '').trim() || '0.0.0-dev';
+    }
+    catch {
+        return '0.0.0-dev';
+    }
+}
+export function resolveCliLaunch(executablePath, platform = process.platform, fileExists = (candidate) => {
+    try {
+        return statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+}) {
+    if (platform !== 'win32' || !/\.(?:cmd|bat)$/i.test(executablePath)) {
+        return { command: executablePath, argsPrefix: [] };
+    }
+    const cliEntry = path.win32.join(path.win32.dirname(executablePath), 'node_modules', '@taskforcehq', 'taskforce', 'dist', 'cli.js');
+    if (!fileExists(cliEntry)) {
+        throw new Error('The Windows Taskforce CLI shim target could not be resolved.');
+    }
+    return { command: process.execPath, argsPrefix: [cliEntry] };
+}
+async function readCliVersion(executablePath, timeoutMs) {
+    const launch = resolveCliLaunch(executablePath);
+    const { stdout } = await execFileAsync(launch.command, [...launch.argsPrefix, '--version'], {
+        timeout: timeoutMs,
+        maxBuffer: 16 * 1024,
+        windowsHide: true,
+    });
+    const version = normalizeVersion(stdout);
+    if (!version)
+        throw new Error('The global Taskforce CLI did not return a valid version.');
+    return version;
+}
+export async function performMcpHandshake(input, dependencies = {}) {
+    const launch = resolveCliLaunch(input.executablePath);
+    const transport = (dependencies.createTransport || ((parameters) => new StdioClientTransport(parameters)))({
+        command: launch.command,
+        args: [...launch.argsPrefix, 'mcp', input.projectRoot],
+        cwd: input.projectRoot,
+        env: {
+            ...getDefaultEnvironment(),
+            TASKFORCE_TENANT_ID: input.tenantId,
+            TASKFORCE_WORKSPACE_ID: input.workspaceId,
+        },
+        stderr: 'ignore',
+    });
+    const client = dependencies.createClient?.()
+        || new Client({ name: 'taskforce-local-cli-health', version: '1.0.0' }, { capabilities: {} });
+    try {
+        await client.connect(transport, { timeout: input.timeoutMs });
+        const tools = await client.listTools(undefined, { timeout: input.timeoutMs });
+        const serverVersion = client.getServerVersion();
+        return {
+            serverName: serverVersion?.name || null,
+            toolNames: tools.tools.map((tool) => tool.name),
+        };
+    }
+    finally {
+        await client.close().catch(() => transport.close().catch(() => undefined));
+    }
+}
+function unusable(input, code, message, executablePath, cliVersion) {
+    return {
+        state: 'unusable',
+        code,
+        message,
+        executablePath,
+        cliVersion,
+        appVersion: input.appVersion,
+        serverName: null,
+        toolCount: null,
+    };
+}
+export async function probeGlobalTaskforceCli(input, dependencies = {}) {
+    const env = input.env || process.env;
+    const timeoutMs = Math.max(1_000, Math.min(15_000, input.timeoutMs || DEFAULT_TIMEOUT_MS));
+    const executablePath = (dependencies.resolveExecutable || resolveExecutableOnPath)('taskforce', env);
+    if (!executablePath) {
+        return unusable(input, 'GLOBAL_CLI_NOT_FOUND', 'Global Taskforce CLI was not found on the server PATH. Use Local / npx or install the current CLI.', null, null);
+    }
+    let cliVersion;
+    try {
+        cliVersion = await (dependencies.readVersion || readCliVersion)(executablePath, timeoutMs);
+    }
+    catch {
+        return unusable(input, 'GLOBAL_CLI_VERSION_FAILED', 'The global Taskforce CLI did not return a valid version. Use Local / npx or install the current CLI.', executablePath, null);
+    }
+    let handshake;
+    try {
+        handshake = await (dependencies.handshake || performMcpHandshake)({
+            executablePath,
+            projectRoot: input.projectRoot,
+            tenantId: input.tenantId,
+            workspaceId: input.workspaceId,
+            timeoutMs,
+        });
+    }
+    catch {
+        return unusable(input, 'GLOBAL_CLI_MCP_HANDSHAKE_FAILED', 'The global Taskforce CLI failed the MCP initialize/tools-list handshake. Use Local / npx or reinstall the current CLI.', executablePath, cliVersion);
+    }
+    const requiredTools = ['get_current_profile', 'list_tasks', 'get_task'];
+    const missingTools = requiredTools.filter((toolName) => !handshake.toolNames.includes(toolName));
+    if (!String(handshake.serverName || '').toLowerCase().startsWith('taskforce') || missingTools.length > 0) {
+        return unusable(input, 'GLOBAL_CLI_MCP_CONTRACT_INVALID', 'The resolved command is not a compatible Taskforce MCP server. Use Local / npx or install the current CLI.', executablePath, cliVersion);
+    }
+    const installedComparable = comparableVersion(cliVersion);
+    const appComparable = comparableVersion(input.appVersion);
+    const versionMismatch = Boolean(installedComparable && appComparable && installedComparable !== appComparable);
+    return {
+        state: versionMismatch ? 'version-mismatch' : 'healthy',
+        code: versionMismatch ? 'GLOBAL_CLI_VERSION_MISMATCH' : 'GLOBAL_CLI_HEALTHY',
+        message: versionMismatch
+            ? `The global Taskforce CLI passed health checks, but version ${cliVersion} does not match app ${input.appVersion}. MCP tools and behavior may differ. Update the global CLI, then check again.`
+            : `Global Taskforce CLI ${cliVersion} passed MCP initialize and tools/list.`,
+        executablePath,
+        cliVersion,
+        appVersion: input.appVersion,
+        serverName: handshake.serverName,
+        toolCount: handshake.toolNames.length,
+    };
+}

package/dist/mcp/localServiceProxy.d.ts

@@ -0,0 +1,23 @@
+import type { Readable, Writable } from 'stream';
+import { discoverOrStartLocalService } from '../service/localServiceClientLifecycle.js';
+export interface LocalServiceProxyOptions {
+    projectRoot: string;
+    env?: NodeJS.ProcessEnv;
+    executablePath: string;
+    cliEntryPath: string;
+    execArgv?: readonly string[];
+    stdin?: Readable;
+    stdout?: Writable;
+    fetch?: typeof fetch;
+    discover?: typeof discoverOrStartLocalService;
+    connectionInstance?: string;
+    maxInFlight?: number;
+    requestTimeoutMs?: number;
+    onFatal?: (error: Error) => void;
+    logError?: (message: string) => void;
+}
+export interface LocalServiceProxyRuntime {
+    close(): Promise<void>;
+    readonly sessionId: string;
+}
+export declare function startLocalServiceMcpProxy(options: LocalServiceProxyOptions): Promise<LocalServiceProxyRuntime>;