@taskforcehq/taskforce 0.3.304 → 0.3.306

package/dist/components/features/DocumentWorkspace.js

@@ -1,168 +1,25 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState, useEffect, useCallback } from 'react';
 import styles from '../../Taskforce.module.css';
 import { DocumentIndex } from './DocumentIndex';
 import { DocumentViewer } from './DocumentViewer';
-import { fetchTaskforceApi } from '../../utils/taskforceApiClient';
-import { logDocumentManagerDebug, resolveDocumentManagerApiBase } from '../../utils/documentManagerApi';
-import { getReadableDocumentName } from '../../utils/documentNames';
-import { DOCUMENT_ATTACHMENT_FILTER_OPTIONS, DOCUMENT_TYPE_FILTER_OPTIONS, } from './documentWorkspaceFilters';
+import { useDocumentWorkspaceController } from './useDocumentWorkspaceController';
 export { DOCUMENT_TYPE_FILTER_OPTIONS, DOCUMENT_ATTACHMENT_FILTER_OPTIONS } from './documentWorkspaceFilters';
-function normalizeDocPath(value) {
-    let decoded = value;
-    try {
-        decoded = decodeURIComponent(value);
-    }
-    catch {
-        decoded = value;
-    }
-    const normalized = decoded
-        .trim()
-        .replace(/\\/g, '/')
-        .replace(/^\/+/, '')
-        .replace(/^\.\//, '')
-        .replace(/^\.taskforce\//, '');
-    return normalized;
-}
-function docPathMatches(candidate, requested) {
-    if (candidate === requested)
-        return true;
-    if (candidate.endsWith(`/${requested}`))
-        return true;
-    if (requested.endsWith(`/${candidate}`))
-        return true;
-    return false;
-}
-function extractAssetIdFromPath(value) {
-    const normalized = normalizeDocPath(String(value || ''));
-    if (!normalized)
-        return null;
-    const match = normalized.match(/(^|\/)(asset-[a-f0-9]{32})(?=[^/]*$)/i);
-    return match?.[2] ? match[2].toLowerCase() : null;
-}
-export function getEffectiveAttachmentState(doc) {
-    if (doc.attachmentState === 'attached' || doc.attachmentState === 'unattached') {
-        return doc.attachmentState;
-    }
-    const attachmentCount = typeof doc.attachmentCount === 'number' && Number.isFinite(doc.attachmentCount)
-        ? doc.attachmentCount
-        : 0;
-    if (attachmentCount > 0 || !!doc.taskId) {
-        return 'attached';
-    }
-    return 'unattached';
-}
-export function DocumentWorkspace({ tasks, apiBaseUrl = '', documents, loading, error, selectedDoc, searchQuery, typeFilters, attachmentFilters, onSearchChange, onSelectDoc, onRefresh, enableTaskGeneration = false }) {
-    const filteredDocs = documents.filter(doc => {
-        const readableName = getReadableDocumentName(doc);
-        const haystack = `${readableName} ${doc.originalFilename || ''}`.toLowerCase();
-        const matchesSearch = !searchQuery || haystack.includes(searchQuery.toLowerCase());
-        const matchesType = typeFilters.length === 0 || typeFilters.includes(doc.docType);
-        const attachmentState = getEffectiveAttachmentState(doc);
-        const matchesAttachment = attachmentFilters.length === 0 || attachmentFilters.includes(attachmentState);
-        return matchesSearch && matchesType && matchesAttachment;
-    });
-    const hasActiveFilters = searchQuery.trim().length > 0 || typeFilters.length > 0 || attachmentFilters.length > 0;
+export function DocumentWorkspace({ tasks, apiBaseUrl = '', documents, loading, error, selectedDoc, searchQuery, hasActiveFilters, onSearchChange, onSelectDoc, onRefresh, onDeleteSelected, enableTaskGeneration = false }) {
     const taskById = new Map(tasks.map(t => [t.id, t]));
-    return (_jsxs("div", { className: styles.docWorkspace, children: [_jsx("div", { className: styles.docIndexPanel, children: _jsx(DocumentIndex, { documents: filteredDocs, selectedDocId: selectedDoc?.id ?? null, loading: loading, error: error, searchQuery: searchQuery, onSearchChange: onSearchChange, onSelect: (doc) => onSelectDoc(doc), onRefresh: onRefresh, taskById: taskById, hasActiveFilters: hasActiveFilters }) }), _jsx("div", { className: styles.docViewerPanel, children: selectedDoc ? (_jsx(DocumentViewer, { doc: selectedDoc, taskTitle: selectedDoc.taskId ? (taskById.get(selectedDoc.taskId)?.title ?? null) : null, apiBaseUrl: apiBaseUrl, onSaved: (_updatedAt) => onRefresh(), onDeleted: () => {
-                        onSelectDoc(null);
-                        void onRefresh();
-                    }, enableTaskGeneration: enableTaskGeneration })) : !loading && (_jsx("div", { className: styles.docViewerEmpty, children: _jsx("p", { className: "tf-empty-copy", children: filteredDocs.length === 0 ? 'No documents match your current filters.' : 'Select a document to view it.' }) })) })] }));
+    return (_jsxs("div", { className: styles.docWorkspace, children: [_jsx("div", { className: styles.docIndexPanel, children: _jsx(DocumentIndex, { documents: documents, selectedDocId: selectedDoc?.id ?? null, loading: loading, error: error, searchQuery: searchQuery, onSearchChange: onSearchChange, onSelect: (doc) => onSelectDoc(doc), onRefresh: onRefresh, taskById: taskById, hasActiveFilters: hasActiveFilters }) }), _jsx("div", { className: styles.docViewerPanel, children: selectedDoc ? (_jsx(DocumentViewer, { doc: selectedDoc, taskTitle: selectedDoc.taskId ? (taskById.get(selectedDoc.taskId)?.title ?? null) : null, tasks: tasks, apiBaseUrl: apiBaseUrl, onSaved: (_updatedAt) => onRefresh(), onDeleted: () => void onDeleteSelected(), enableTaskGeneration: enableTaskGeneration })) : !loading && (_jsx("div", { className: styles.docViewerEmpty, children: _jsx("p", { className: "tf-empty-copy", children: documents.length === 0 ? 'No documents match your current filters.' : 'Select a document to view it.' }) })) })] }));
 }
 export function DocumentWorkspaceShell({ tasks, runtimeMode = 'local', apiBaseUrl = '', cloudAuthBaseUrl = '', typeFilters: controlledTypeFilters, attachmentFilters: controlledAttachmentFilters, onTypeFiltersChange, onAttachmentFiltersChange, requestedDocPath = null, requestedDocAssetId = null, onRequestedDocHandled, enableTaskGeneration = false }) {
-    const [documents, setDocuments] = useState([]);
-    const [loading, setLoading] = useState(true);
-    const [error, setError] = useState(null);
-    const [selectedDoc, setSelectedDoc] = useState(null);
-    const [searchQuery, setSearchQuery] = useState('');
-    const [internalTypeFilters, setInternalTypeFilters] = useState(() => DOCUMENT_TYPE_FILTER_OPTIONS.map((option) => option.value));
-    const [internalAttachmentFilters, setInternalAttachmentFilters] = useState(() => DOCUMENT_ATTACHMENT_FILTER_OPTIONS.map((option) => option.value));
-    const documentApiBaseUrl = resolveDocumentManagerApiBase({
+    const { documentApiBaseUrl, filteredDocs, loading, error, selectedDoc, searchQuery, hasActiveFilters, setSearchQuery, fetchDocuments, selectDoc, handleDeleteSelected, } = useDocumentWorkspaceController({
         runtimeMode,
         apiBaseUrl,
         cloudAuthBaseUrl,
+        typeFilters: controlledTypeFilters,
+        attachmentFilters: controlledAttachmentFilters,
+        onTypeFiltersChange,
+        onAttachmentFiltersChange,
+        requestedDocPath,
+        requestedDocAssetId,
+        onRequestedDocHandled,
     });
-    const typeFilters = controlledTypeFilters ?? internalTypeFilters;
-    const attachmentFilters = controlledAttachmentFilters ?? internalAttachmentFilters;
-    const handleTypeFiltersChange = onTypeFiltersChange ?? setInternalTypeFilters;
-    const handleAttachmentFiltersChange = onAttachmentFiltersChange ?? setInternalAttachmentFilters;
-    const fetchDocuments = useCallback(async () => {
-        setLoading(true);
-        setError(null);
-        try {
-            const res = await fetchTaskforceApi('/api/taskforce/documents', {
-                credentials: 'include',
-            }, documentApiBaseUrl);
-            if (!res.ok)
-                throw new Error(`Failed to load documents (${res.status})`);
-            const data = await res.json();
-            const nextDocuments = data.documents || [];
-            logDocumentManagerDebug('list.loaded', {
-                runtimeMode,
-                apiBaseUrl: documentApiBaseUrl || '(same-origin)',
-                count: Array.isArray(nextDocuments) ? nextDocuments.length : 0,
-            });
-            setDocuments(nextDocuments);
-        }
-        catch (e) {
-            setError(e?.message || 'Failed to load documents');
-            logDocumentManagerDebug('list.error', {
-                runtimeMode,
-                apiBaseUrl: documentApiBaseUrl || '(same-origin)',
-                message: e?.message || 'Failed to load documents',
-            });
-        }
-        finally {
-            setLoading(false);
-        }
-    }, [documentApiBaseUrl, runtimeMode]);
-    useEffect(() => {
-        fetchDocuments();
-    }, [fetchDocuments]);
-    // Auto-select first doc when list loads
-    useEffect(() => {
-        if (requestedDocPath || requestedDocAssetId)
-            return;
-        if (!selectedDoc && documents.length > 0) {
-            setSelectedDoc(documents[0]);
-        }
-    }, [documents, selectedDoc, requestedDocAssetId, requestedDocPath]);
-    useEffect(() => {
-        if ((!requestedDocPath && !requestedDocAssetId) || documents.length === 0)
-            return;
-        const requested = requestedDocPath ? normalizeDocPath(requestedDocPath) : '';
-        const requestedAssetId = String(requestedDocAssetId || '').trim().toLowerCase()
-            || extractAssetIdFromPath(requestedDocPath);
-        const matched = documents.find((doc) => {
-            const candidateAssetId = extractAssetIdFromPath(doc.fsPath) || String(doc.assetId || '').trim().toLowerCase() || null;
-            if (requestedAssetId && candidateAssetId && candidateAssetId === requestedAssetId)
-                return true;
-            if (!requested)
-                return false;
-            const candidate = normalizeDocPath(doc.fsPath);
-            return docPathMatches(candidate, requested);
-        });
-        if (matched) {
-            setSelectedDoc(matched);
-            onRequestedDocHandled?.();
-            return;
-        }
-    }, [requestedDocAssetId, requestedDocPath, documents, onRequestedDocHandled]);
-    useEffect(() => {
-        if ((requestedDocPath || requestedDocAssetId) && !selectedDoc)
-            return;
-        const filtered = documents.filter((doc) => {
-            const readableName = getReadableDocumentName(doc);
-            const haystack = `${readableName} ${doc.originalFilename || ''}`.toLowerCase();
-            const matchesSearch = !searchQuery || haystack.includes(searchQuery.toLowerCase());
-            const matchesType = typeFilters.length === 0 || typeFilters.includes(doc.docType);
-            const attachmentState = getEffectiveAttachmentState(doc);
-            const matchesAttachment = attachmentFilters.length === 0 || attachmentFilters.includes(attachmentState);
-            return matchesSearch && matchesType && matchesAttachment;
-        });
-        if (selectedDoc && filtered.some((doc) => doc.id === selectedDoc.id))
-            return;
-        setSelectedDoc(filtered[0] ?? null);
-    }, [attachmentFilters, documents, requestedDocAssetId, requestedDocPath, searchQuery, selectedDoc, typeFilters]);
-    return (_jsx(DocumentWorkspace, { tasks: tasks, apiBaseUrl: documentApiBaseUrl, documents: documents, loading: loading, error: error, selectedDoc: selectedDoc, searchQuery: searchQuery, typeFilters: typeFilters, attachmentFilters: attachmentFilters, onSearchChange: setSearchQuery, onSelectDoc: setSelectedDoc, onRefresh: fetchDocuments, enableTaskGeneration: enableTaskGeneration }));
+    return (_jsx(DocumentWorkspace, { tasks: tasks, apiBaseUrl: documentApiBaseUrl, documents: filteredDocs, loading: loading, error: error, selectedDoc: selectedDoc, searchQuery: searchQuery, hasActiveFilters: hasActiveFilters, onSearchChange: setSearchQuery, onSelectDoc: selectDoc, onRefresh: fetchDocuments, onDeleteSelected: handleDeleteSelected, enableTaskGeneration: enableTaskGeneration }));
 }

package/dist/components/features/DocumentWorkspace.test.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
 import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -44,6 +44,9 @@ function createEmptyReviewSessionsResponse() {
         json: async () => ({ sessions: [] }),
     };
 }
+function renderDocumentWorkspace(props) {
+    return render(_jsx(DocumentWorkspace, { tasks: props.tasks ?? [], documents: props.documents, loading: false, error: null, selectedDoc: props.selectedDoc ?? null, searchQuery: props.searchQuery ?? '', hasActiveFilters: props.hasActiveFilters ?? false, onSearchChange: props.onSearchChange ?? (() => { }), onSelectDoc: props.onSelectDoc ?? (() => { }), onRefresh: props.onRefresh ?? (() => { }), onDeleteSelected: props.onDeleteSelected ?? (() => { }) }));
+}
 describe('Document workspace management', () => {
     beforeEach(() => {
         fetchTaskforceApi.mockReset();
@@ -87,7 +90,7 @@ describe('Document workspace management', () => {
         ];
         function Harness() {
             const [selectedDoc, setSelectedDoc] = useState(null);
-            return (_jsx(DocumentWorkspace, { tasks: [{ id: 'task-1', title: 'Parent task' }], documents: docs, loading: false, error: null, selectedDoc: selectedDoc, searchQuery: "", typeFilters: [], attachmentFilters: ['unattached'], onSearchChange: () => { }, onSelectDoc: setSelectedDoc, onRefresh: () => { } }));
+            return (_jsx(DocumentWorkspace, { tasks: [{ id: 'task-1', title: 'Parent task' }], documents: docs.filter((doc) => doc.attachmentState === 'unattached'), loading: false, error: null, selectedDoc: selectedDoc, searchQuery: "", hasActiveFilters: true, onSearchChange: () => { }, onSelectDoc: setSelectedDoc, onRefresh: () => { }, onDeleteSelected: () => { } }));
         }
         render(_jsx(Harness, {}));
         expect(screen.getByRole('button', { name: /Orphan notes/i })).toBeInTheDocument();
@@ -95,13 +98,13 @@ describe('Document workspace management', () => {
         expect(screen.getByText('Unattached')).toBeInTheDocument();
     });
     it('keeps document search in the index without duplicate filter controls', () => {
-        render(_jsx(DocumentWorkspace, { tasks: [], documents: [createDoc()], loading: false, error: null, selectedDoc: null, searchQuery: "", typeFilters: [], attachmentFilters: [], onSearchChange: () => { }, onSelectDoc: () => { }, onRefresh: () => { } }));
+        renderDocumentWorkspace({ documents: [createDoc()] });
         expect(screen.getByPlaceholderText('Search documents…')).toBeInTheDocument();
         expect(screen.queryByRole('button', { name: 'Attached' })).not.toBeInTheDocument();
         expect(screen.queryByRole('button', { name: 'Plans' })).not.toBeInTheDocument();
     });
     it('shows the document reference badge in the bottom metadata row of index cards', () => {
-        render(_jsx(DocumentWorkspace, { tasks: [], documents: [createDoc({ referenceLabel: 'D-42' })], loading: false, error: null, selectedDoc: null, searchQuery: "", typeFilters: [], attachmentFilters: [], onSearchChange: () => { }, onSelectDoc: () => { }, onRefresh: () => { } }));
+        renderDocumentWorkspace({ documents: [createDoc({ referenceLabel: 'D-42' })] });
         expect(screen.getByText('D-42')).toBeInTheDocument();
         expect(screen.getByText(/64B/)).toBeInTheDocument();
     });
@@ -142,6 +145,82 @@ describe('Document workspace management', () => {
         confirmSpy.mockRestore();
         alertSpy.mockRestore();
     });
+    it('opens an attach modal from the document viewer and attaches the document to a task', async () => {
+        const user = userEvent.setup();
+        fetchTaskforceApi
+            .mockResolvedValueOnce({
+            ok: true,
+            text: async () => '# Example\n',
+        })
+            .mockResolvedValueOnce(createEmptyReviewSessionsResponse())
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ success: true, attached: true, alreadyAttached: false }),
+        });
+        const onSaved = vi.fn();
+        render(_jsx(DocumentViewer, { doc: createDoc({
+                id: 'doc-attach',
+                assetId: 'asset-doc-attach',
+                attachmentCount: 0,
+                attachmentState: 'unattached',
+            }), taskTitle: null, tasks: [
+                { id: 'task-1', title: 'First attach target' },
+                { id: 'task-2', title: 'Second attach target' },
+            ], onSaved: onSaved }));
+        await waitFor(() => expect(fetchTaskforceApi).toHaveBeenCalledWith('/api/taskforce/documents/asset-doc-1/content', { credentials: 'same-origin' }, ''));
+        await user.click(screen.getByRole('button', { name: /^Attach$/i }));
+        expect(screen.getByText(/Attach this document to a task from the document manager/i)).toBeInTheDocument();
+        await user.type(screen.getByPlaceholderText('Search tasks…'), 'Second');
+        await user.click(screen.getByRole('button', { name: /Second attach target/i }));
+        await waitFor(() => expect(fetchTaskforceApi).toHaveBeenLastCalledWith('/api/taskforce/documents/asset-doc-attach/attach', expect.objectContaining({
+            method: 'POST',
+            credentials: 'include',
+        }), ''));
+        expect(onSaved).toHaveBeenCalled();
+    });
+    it('shows delete and unlink for attached docs and sends forceDetach on delete', async () => {
+        const user = userEvent.setup();
+        fetchTaskforceApi
+            .mockResolvedValueOnce({
+            ok: true,
+            text: async () => '# Example\n',
+        })
+            .mockResolvedValueOnce(createEmptyReviewSessionsResponse())
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ success: true, softDeleted: true, detachedTaskCount: 2 }),
+        });
+        const confirmSpy = vi.spyOn(window, 'confirm').mockReturnValue(true);
+        const alertSpy = vi.spyOn(window, 'alert').mockImplementation(() => { });
+        const onDeleted = vi.fn();
+        render(_jsx(DocumentViewer, { doc: {
+                id: 'doc-attached',
+                assetId: 'asset-doc-attached',
+                fsPath: 'workspaces/default/assets/documents/doc-attached.md',
+                apiUrl: '/api/taskforce/documents/asset-doc-attached/content',
+                taskId: 'task-1',
+                displayName: 'Attached spec',
+                title: 'Attached spec',
+                docType: 'other',
+                sizeBytes: 64,
+                updatedAt: '2026-03-19T11:00:00.000Z',
+                editable: true,
+                attachmentCount: 2,
+                attachmentState: 'attached',
+            }, taskTitle: null, onDeleted: onDeleted }));
+        await waitFor(() => expect(fetchTaskforceApi).toHaveBeenCalledWith('/api/taskforce/documents/asset-doc-attached/content', { credentials: 'same-origin' }, ''));
+        await user.click(screen.getByRole('button', { name: /Delete & Unlink/i }));
+        await waitFor(() => expect(fetchTaskforceApi).toHaveBeenLastCalledWith('/api/taskforce/documents/asset-doc-attached', expect.objectContaining({
+            method: 'DELETE',
+            credentials: 'include',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ forceDetach: true })
+        }), ''));
+        expect(confirmSpy).toHaveBeenCalledWith(expect.stringContaining('remove it from 2 linked tasks'));
+        expect(onDeleted).toHaveBeenCalled();
+        confirmSpy.mockRestore();
+        alertSpy.mockRestore();
+    });
     it('uses same-origin document routes in local runtime even when an api base is configured', async () => {
         const user = userEvent.setup();
         fetchTaskforceApi
@@ -226,6 +305,46 @@ describe('Document workspace management', () => {
         expect(await screen.findByText('Please tighten the rollout section.')).toBeInTheDocument();
         expect(screen.getByText('Lines 18-24')).toBeInTheDocument();
     });
+    it('toggles the review sidebar from the document header', async () => {
+        const user = userEvent.setup();
+        fetchTaskforceApi
+            .mockResolvedValueOnce({
+            ok: true,
+            text: async () => '# Example\n',
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                sessions: [{
+                        id: 'review-1',
+                        tenantId: 'default',
+                        workspaceId: 'default',
+                        assetId: 'asset-doc-1',
+                        documentId: 'doc-1',
+                        documentVersion: 1,
+                        title: 'Review 1',
+                        status: 'open',
+                        createdByActorId: 'user',
+                        updatedByActorId: 'user',
+                        createdByActor: null,
+                        updatedByActor: null,
+                        createdAt: '2026-03-19T12:00:00.000Z',
+                        updatedAt: '2026-03-19T12:05:00.000Z',
+                        deletedAt: null,
+                        comments: [],
+                    }],
+            }),
+        });
+        render(_jsx(DocumentViewer, { doc: createDoc(), taskTitle: null }));
+        expect(await screen.findByText('Review & Comments')).toBeInTheDocument();
+        expect(screen.getByPlaceholderText('Add a comment for this document review…')).toBeInTheDocument();
+        await user.click(screen.getByRole('button', { name: 'Hide Review' }));
+        expect(screen.queryByText('Review & Comments')).not.toBeInTheDocument();
+        expect(screen.queryByPlaceholderText('Add a comment for this document review…')).not.toBeInTheDocument();
+        await user.click(screen.getByRole('button', { name: 'Show Review' }));
+        expect(await screen.findByText('Review & Comments')).toBeInTheDocument();
+        expect(screen.getByPlaceholderText('Add a comment for this document review…')).toBeInTheDocument();
+    });
     it('creates a review session and posts comments from the document viewer', async () => {
         const user = userEvent.setup();
         fetchTaskforceApi
@@ -1087,13 +1206,114 @@ Body copy.
                 attachmentCount: 0,
             },
         ];
-        const { rerender } = render(_jsx(DocumentWorkspace, { tasks: [{ id: 'task-1', title: 'Parent task' }], documents: docs, loading: false, error: null, selectedDoc: null, searchQuery: "", typeFilters: [], attachmentFilters: ['attached'], onSearchChange: () => { }, onSelectDoc: () => { }, onRefresh: () => { } }));
+        const { rerender } = renderDocumentWorkspace({
+            tasks: [{ id: 'task-1', title: 'Parent task' }],
+            documents: docs.filter((doc) => doc.taskId),
+            hasActiveFilters: true,
+        });
         expect(screen.getByText('Attached fallback')).toBeInTheDocument();
         expect(screen.queryByText('Unattached fallback')).not.toBeInTheDocument();
-        rerender(_jsx(DocumentWorkspace, { tasks: [{ id: 'task-1', title: 'Parent task' }], documents: docs, loading: false, error: null, selectedDoc: null, searchQuery: "", typeFilters: [], attachmentFilters: ['unattached'], onSearchChange: () => { }, onSelectDoc: () => { }, onRefresh: () => { } }));
+        rerender(_jsx(DocumentWorkspace, { tasks: [{ id: 'task-1', title: 'Parent task' }], documents: docs.filter((doc) => !doc.taskId), loading: false, error: null, selectedDoc: null, searchQuery: "", hasActiveFilters: true, onSearchChange: () => { }, onSelectDoc: () => { }, onRefresh: () => { }, onDeleteSelected: () => { } }));
         expect(screen.getByText('Unattached fallback')).toBeInTheDocument();
         expect(screen.queryByText('Attached fallback')).not.toBeInTheDocument();
     });
+    it('switches the active document when a different index item is selected', async () => {
+        const user = userEvent.setup();
+        const docs = [
+            createDoc({
+                id: 'doc-first',
+                assetId: 'asset-doc-first',
+                apiUrl: '/api/taskforce/documents/asset-doc-first/content',
+                displayName: 'First notes',
+                title: 'First notes',
+            }),
+            createDoc({
+                id: 'doc-second',
+                assetId: 'asset-doc-second',
+                apiUrl: '/api/taskforce/documents/asset-doc-second/content',
+                displayName: 'Second notes',
+                title: 'Second notes',
+                fsPath: 'workspaces/default/assets/documents/second-notes.md',
+            }),
+        ];
+        fetchTaskforceApi
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ documents: docs }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            text: async () => '# First content\n',
+        })
+            .mockResolvedValueOnce(createEmptyReviewSessionsResponse())
+            .mockResolvedValueOnce({
+            ok: true,
+            text: async () => '# Second content\n',
+        })
+            .mockResolvedValueOnce(createEmptyReviewSessionsResponse());
+        render(_jsx(DocumentWorkspaceShell, { tasks: [], runtimeMode: "local" }));
+        expect(await screen.findByText('First content')).toBeInTheDocument();
+        await user.click(screen.getByRole('button', { name: /Second notes/i }));
+        expect(await screen.findByText('Second content')).toBeInTheDocument();
+        await waitFor(() => expect(fetchTaskforceApi).toHaveBeenNthCalledWith(4, '/api/taskforce/documents/asset-doc-second/content', expect.objectContaining({ credentials: 'same-origin' }), ''));
+    });
+    it('returns to the remaining filtered document when the active selection is filtered out', async () => {
+        const user = userEvent.setup();
+        const docs = [
+            createDoc({
+                id: 'doc-attached-return',
+                assetId: 'asset-doc-attached-return',
+                apiUrl: '/api/taskforce/documents/asset-doc-attached-return/content',
+                displayName: 'Attached return doc',
+                title: 'Attached return doc',
+                attachmentCount: 1,
+                attachmentState: 'attached',
+                taskId: 'task-1',
+            }),
+            createDoc({
+                id: 'doc-unattached-return',
+                assetId: 'asset-doc-unattached-return',
+                apiUrl: '/api/taskforce/documents/asset-doc-unattached-return/content',
+                displayName: 'Unattached return doc',
+                title: 'Unattached return doc',
+                fsPath: 'workspaces/default/assets/documents/unattached-return-doc.md',
+                attachmentCount: 0,
+                attachmentState: 'unattached',
+                taskId: null,
+            }),
+        ];
+        function Harness() {
+            const [attachmentFilters, setAttachmentFilters] = useState([]);
+            return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", onClick: () => setAttachmentFilters(['attached']), children: "Show attached only" }), _jsx(DocumentWorkspaceShell, { tasks: [{ id: 'task-1', title: 'Parent task' }], runtimeMode: "local", attachmentFilters: attachmentFilters })] }));
+        }
+        fetchTaskforceApi
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ documents: docs }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            text: async () => '# Attached return content\n',
+        })
+            .mockResolvedValueOnce(createEmptyReviewSessionsResponse())
+            .mockResolvedValueOnce({
+            ok: true,
+            text: async () => '# Unattached return content\n',
+        })
+            .mockResolvedValueOnce(createEmptyReviewSessionsResponse())
+            .mockResolvedValueOnce({
+            ok: true,
+            text: async () => '# Attached return content\n',
+        })
+            .mockResolvedValueOnce(createEmptyReviewSessionsResponse());
+        render(_jsx(Harness, {}));
+        expect(await screen.findByText('Attached return content')).toBeInTheDocument();
+        await user.click(screen.getByRole('button', { name: /Unattached return doc/i }));
+        expect(await screen.findByText('Unattached return content')).toBeInTheDocument();
+        await user.click(screen.getByRole('button', { name: /Show attached only/i }));
+        expect(await screen.findByText('Attached return content')).toBeInTheDocument();
+        await waitFor(() => expect(fetchTaskforceApi).toHaveBeenNthCalledWith(6, '/api/taskforce/documents/asset-doc-attached-return/content', expect.objectContaining({ credentials: 'same-origin' }), ''));
+    });
     it('selects a requested document by asset id when normalized paths differ', async () => {
         const docs = [
             {

package/dist/components/features/TaskSettings.js

@@ -534,13 +534,36 @@ export function TaskSettings(props) {
                 const workspaceName = typeof details?.tokenWorkspaceId === 'string'
                     ? String(details.tokenWorkspaceId)
                     : undefined;
-                const message = payload?.code === 'MCP_TOKEN_MISSING_SCOPES' && missingScopes.length > 0
+                const endpoint = typeof details?.endpoint === 'string'
+                    ? String(details.endpoint)
+                    : cloudMcpEndpoint;
+                let message = payload?.code === 'MCP_TOKEN_MISSING_SCOPES' && missingScopes.length > 0
                     ? `Token is missing required scopes: ${missingScopes.join(', ')}.`
                     : String(payload?.error || 'Failed to test MCP connection.');
+                let followup;
+                if (payload?.code === 'MCP_ENDPOINT_GATEWAY_ERROR') {
+                    message = 'The dedicated MCP host is responding with a gateway error.';
+                    followup = 'This usually means the cloud MCP service is degraded. Retry shortly, and if it keeps failing treat it as an environment incident rather than a bad token.';
+                }
+                else if (payload?.code === 'MCP_ENDPOINT_TIMEOUT') {
+                    message = 'The dedicated MCP host timed out during MCP initialization.';
+                    followup = 'This usually points to a degraded or overloaded cloud MCP service.';
+                }
+                else if (payload?.code === 'MCP_ENDPOINT_UNREACHABLE') {
+                    message = 'The dedicated MCP host could not be reached.';
+                    followup = 'Check the cloud MCP hostname and environment health before rotating credentials.';
+                }
+                else if (payload?.code === 'MCP_ENDPOINT_REJECTED_VALIDATED_TOKEN') {
+                    message = 'The dedicated MCP host rejected a token that validated locally.';
+                    followup = 'This suggests the MCP host is stale, routed incorrectly, or out of sync with auth data.';
+                }
                 setMcpConnectionResult({
                     type: 'error',
                     message,
                     workspaceName,
+                    endpoint,
+                    errorCode: typeof payload?.code === 'string' ? String(payload.code) : undefined,
+                    followup,
                 });
                 return;
             }
@@ -551,12 +574,15 @@ export function TaskSettings(props) {
                 scopes: Array.isArray(result?.scopes) ? result.scopes.map((scope) => String(scope)) : [],
                 workspaceName: typeof result?.workspaceName === 'string' ? String(result.workspaceName) : '',
                 workspaceId: typeof result?.workspaceId === 'string' ? String(result.workspaceId) : '',
+                endpoint: typeof result?.endpoint === 'string' ? String(result.endpoint) : cloudMcpEndpoint,
             });
         }
         catch {
             setMcpConnectionResult({
                 type: 'error',
-                message: 'Failed to test MCP connection.'
+                message: 'Failed to test MCP connection.',
+                endpoint: cloudMcpEndpoint,
+                followup: 'The settings page could not complete the connection probe. Check your network connection and the selected cloud environment.'
             });
         }
         finally {
@@ -893,7 +919,7 @@ export function TaskSettings(props) {
                                                                         } })] }), _jsxs("div", { className: styles.marginTop12, style: { display: 'flex', gap: '8px', flexWrap: 'wrap', justifyContent: 'flex-end' }, children: [generatedTokenValue && (_jsx("button", { className: styles.copyBtn, onClick: () => {
                                                                             setMcpConnectionToken(generatedTokenValue);
                                                                             setMcpConnectionResult(null);
-                                                                        }, children: "Use Generated Token" })), _jsxs("button", { className: styles.copyBtn, onClick: () => void handleTestMcpConnection(), disabled: mcpConnectionBusy, children: [mcpConnectionBusy ? _jsx(Loader2, { size: 14, className: styles.spinIcon }) : _jsx(Zap, { size: 14 }), "Test Connection"] })] }), mcpConnectionResult && (_jsxs("div", { className: `${mcpConnectionResult.type === 'success' ? styles.successMessage : styles.errorMessage} ${styles.marginTop12}`, children: [mcpConnectionResult.type === 'success' ? _jsx(Check, { size: 14 }) : _jsx(AlertTriangle, { size: 14 }), _jsxs("div", { children: [_jsx("div", { children: mcpConnectionResult.message }), mcpConnectionResult.type === 'success' && (mcpConnectionResult.workspaceName || mcpConnectionResult.workspaceId) && (_jsxs("div", { className: styles.settingHelper, children: ["Workspace: ", mcpConnectionResult.workspaceName || mcpConnectionResult.workspaceId, mcpConnectionResult.workspaceId ? ` (${mcpConnectionResult.workspaceId})` : ''] })), mcpConnectionResult.type === 'success' && Array.isArray(mcpConnectionResult.scopes) && mcpConnectionResult.scopes.length > 0 && (_jsxs("div", { className: styles.settingHelper, children: ["Granted scopes: ", mcpConnectionResult.scopes.join(', ')] }))] })] }))] }))] }), _jsxs("div", { className: `${styles.settingGroup} ${styles.marginTop16}`, children: [_jsxs("div", { className: styles.toggleHeading, onClick: () => setShowMcpTokensList((prev) => !prev), onKeyDown: (e) => {
+                                                                        }, children: "Use Generated Token" })), _jsxs("button", { className: styles.copyBtn, onClick: () => void handleTestMcpConnection(), disabled: mcpConnectionBusy, children: [mcpConnectionBusy ? _jsx(Loader2, { size: 14, className: styles.spinIcon }) : _jsx(Zap, { size: 14 }), "Test Connection"] })] }), mcpConnectionResult && (_jsxs("div", { className: `${mcpConnectionResult.type === 'success' ? styles.successMessage : styles.errorMessage} ${styles.marginTop12}`, children: [mcpConnectionResult.type === 'success' ? _jsx(Check, { size: 14 }) : _jsx(AlertTriangle, { size: 14 }), _jsxs("div", { children: [_jsx("div", { children: mcpConnectionResult.message }), mcpConnectionResult.type === 'success' && (mcpConnectionResult.workspaceName || mcpConnectionResult.workspaceId) && (_jsxs("div", { className: styles.settingHelper, children: ["Workspace: ", mcpConnectionResult.workspaceName || mcpConnectionResult.workspaceId, mcpConnectionResult.workspaceId ? ` (${mcpConnectionResult.workspaceId})` : ''] })), mcpConnectionResult.type === 'success' && Array.isArray(mcpConnectionResult.scopes) && mcpConnectionResult.scopes.length > 0 && (_jsxs("div", { className: styles.settingHelper, children: ["Granted scopes: ", mcpConnectionResult.scopes.join(', ')] })), mcpConnectionResult.endpoint && (_jsxs("div", { className: styles.settingHelper, children: ["Endpoint: ", mcpConnectionResult.endpoint] })), mcpConnectionResult.type === 'error' && mcpConnectionResult.errorCode && (_jsxs("div", { className: styles.settingHelper, children: ["Error code: ", mcpConnectionResult.errorCode] })), mcpConnectionResult.type === 'error' && mcpConnectionResult.followup && (_jsx("div", { className: styles.settingHelper, children: mcpConnectionResult.followup }))] })] }))] }))] }), _jsxs("div", { className: `${styles.settingGroup} ${styles.marginTop16}`, children: [_jsxs("div", { className: styles.toggleHeading, onClick: () => setShowMcpTokensList((prev) => !prev), onKeyDown: (e) => {
                                                             if (e.key === 'Enter' || e.key === ' ') {
                                                                 e.preventDefault();
                                                                 setShowMcpTokensList((prev) => !prev);

package/dist/components/features/TaskSettings.test.js

@@ -970,7 +970,8 @@ describe('TaskSettings Component', () => {
                         result: {
                             workspaceName: 'Workspace Alpha',
                             workspaceId: 'workspace-alpha',
-                            scopes: ['tasks:read', 'tasks:write', 'workspace:read']
+                            scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
+                            endpoint: 'https://performance-mcp.taskforcehq.ai/mcp'
                         }
                     })
                 };
@@ -999,6 +1000,46 @@ describe('TaskSettings Component', () => {
         }));
         expect(await screen.findByText('Connection looks good for this workspace.')).toBeInTheDocument();
         expect(screen.getByText(/Granted scopes: tasks:read, tasks:write, workspace:read/i)).toBeInTheDocument();
+        expect(screen.getByText(/Endpoint: https:\/\/performance-mcp\.taskforcehq\.ai\/mcp/i)).toBeInTheDocument();
+    }, 10000);
+    it('4.23d2 MCP test connection shows a dedicated-host incident message when the endpoint returns a gateway failure', async () => {
+        const fetchCloudAuthApi = vi.fn(async (path) => {
+            if (path === '/api/taskforce/settings/mcp/test-connection') {
+                return {
+                    ok: false,
+                    json: async () => ({
+                        code: 'MCP_ENDPOINT_GATEWAY_ERROR',
+                        error: 'Cloud MCP endpoint https://performance-mcp.taskforcehq.ai/mcp returned 502.',
+                        details: {
+                            endpoint: 'https://performance-mcp.taskforcehq.ai/mcp',
+                            upstreamStatus: 502
+                        }
+                    })
+                };
+            }
+            return {
+                ok: true,
+                json: async () => ({ items: [] })
+            };
+        });
+        const user = userEvent.setup();
+        renderComponent({
+            settingsModel: {
+                runtimeMode: 'local',
+                isAuthenticated: true,
+                currentWorkspaceName: 'Workspace Alpha',
+                cloudMcpBaseUrl: 'https://performance-mcp.taskforcehq.ai',
+                fetchCloudAuthApi
+            }
+        });
+        await openCloudMcpSettings(user);
+        await user.click(screen.getByRole('button', { name: 'Test Connection' }));
+        await user.type(await screen.findByPlaceholderText('tfmcp_xxxxx_replace-me'), 'tfmcp_example_secret');
+        await user.click(screen.getAllByRole('button', { name: 'Test Connection' })[1]);
+        expect(await screen.findByText('The dedicated MCP host is responding with a gateway error.')).toBeInTheDocument();
+        expect(screen.getByText(/Endpoint: https:\/\/performance-mcp\.taskforcehq\.ai\/mcp/i)).toBeInTheDocument();
+        expect(screen.getByText(/Error code: MCP_ENDPOINT_GATEWAY_ERROR/i)).toBeInTheDocument();
+        expect(screen.getByText(/This usually means the cloud MCP service is degraded/i)).toBeInTheDocument();
     }, 10000);
     it('4.23e Antigravity uses serverUrl instead of transport in the cloud snippet', async () => {
         const fetchCloudAuthApi = vi.fn(async () => ({

package/dist/components/features/documentWorkspaceModel.d.ts

@@ -0,0 +1,24 @@
+import type { DocumentAttachmentFilter, DocumentTypeFilter } from './documentWorkspaceFilters';
+export interface DocMeta {
+    id: string;
+    assetId?: string;
+    referenceNumber?: number | null;
+    referenceLabel?: string | null;
+    fsPath: string;
+    apiUrl: string;
+    taskId: string | null;
+    displayName: string;
+    originalFilename?: string | null;
+    title: string;
+    docType: 'implementation-plan' | 'review' | 'walkthrough' | 'planning' | 'other';
+    sizeBytes: number;
+    updatedAt: string | null;
+    editable?: boolean;
+    attachmentCount?: number;
+    attachmentState?: 'attached' | 'unattached';
+}
+export declare function normalizeDocPath(value: string): string;
+export declare function docPathMatches(candidate: string, requested: string): boolean;
+export declare function extractAssetIdFromPath(value: string | null | undefined): string | null;
+export declare function getEffectiveAttachmentState(doc: Pick<DocMeta, 'attachmentState' | 'attachmentCount' | 'taskId'>): 'attached' | 'unattached';
+export declare function filterDocuments(documents: DocMeta[], searchQuery: string, typeFilters: DocumentTypeFilter[], attachmentFilters: DocumentAttachmentFilter[]): DocMeta[];