@taskforcehq/taskforce 0.3.328 → 0.3.330

package/dist/hooks/useSyncOrchestrator.js

@@ -156,6 +156,29 @@ export function useSyncOrchestrator(input) {
     const bootstrapPhaseStartedAtRef = useRef(null);
     const bootstrapLastProgressAtRef = useRef(null);
     const lastBootstrapPhaseRef = useRef('idle');
+    // Incremented every time the workspace-switch reset effect runs (including a
+    // switch back to the same workspace id). Reference-snapshot refreshes capture
+    // this value before their first await and refuse to commit a response whose
+    // generation has since moved on, so a stale/raced fetch can never overwrite a
+    // fresher (or freshly-reset) snapshot with data for the wrong workspace visit.
+    const workspaceSyncGenerationRef = useRef(0);
+    // Positive completeness signal for the document/asset snapshots, mirrored in a
+    // ref (not React state) so buildWorkspaceSyncPayload's ref-only read pattern
+    // can't observe a stale value from an earlier render's closure. Only ever set
+    // true immediately alongside a validated, non-stale successful refresh; reset
+    // to false whenever the workspace-switch effect invalidates the current
+    // generation. buildWorkspaceSyncPayloadModel refuses to compute any deletions
+    // for a domain while its completeness flag is false.
+    const workspaceSyncDocumentsSnapshotCompleteRef = useRef(false);
+    const workspaceSyncAssetsSnapshotCompleteRef = useRef(false);
+    // Per-domain monotonic request counters. Incremented at the start of every
+    // refresh call (independent of workspaceSyncGenerationRef, which only tracks
+    // workspace switches). Guards against two overlapping in-flight requests for
+    // the SAME workspace/generation — e.g. an interval tick firing while an
+    // event-triggered refresh is still in flight — where an older response could
+    // otherwise resolve after a newer one and overwrite fresher data.
+    const workspaceSyncDocumentsRequestSeqRef = useRef(0);
+    const workspaceSyncAssetsRequestSeqRef = useRef(0);
     // === SECTION: User global settings sync ===
     const clearUserSettingsRetry = useCallback(() => {
         if (userSettingsRetryTimeoutRef.current !== null) {
@@ -256,6 +279,7 @@ export function useSyncOrchestrator(input) {
     const workspaceLastPushedInitiativeWatermarksRef = useRef(new Map());
     const workspaceLastPushedWorkstreamIdsRef = useRef(new Set());
     const workspaceLastPushedWorkstreamWatermarksRef = useRef(new Map());
+    const workspaceLastPushedPlanningIdentityWatermarksRef = useRef(new Map());
     const workspaceLastPushedAiProfileIdsRef = useRef(new Set());
     const workspaceLastPushedAiProfileWatermarksRef = useRef(new Map());
     const workspaceLastPushedAiProfileChangeKeysRef = useRef(new Map());
@@ -288,6 +312,7 @@ export function useSyncOrchestrator(input) {
         workspaceLastPushedInitiativeWatermarksRef.current = persisted.initiativeWatermarks;
         workspaceLastPushedWorkstreamIdsRef.current = new Set(Array.from(persisted.workstreamWatermarks.keys()));
         workspaceLastPushedWorkstreamWatermarksRef.current = persisted.workstreamWatermarks;
+        workspaceLastPushedPlanningIdentityWatermarksRef.current = new Map(persisted.planningIdentityWatermarks || []);
         workspaceLastPushedAiProfileIdsRef.current = new Set(Array.from(persisted.aiProfileWatermarks.keys()));
         workspaceLastPushedAiProfileWatermarksRef.current = persisted.aiProfileWatermarks;
         workspaceLastPushedAiProfileChangeKeysRef.current = persisted.aiProfileChangeKeys || new Map();
@@ -319,6 +344,7 @@ export function useSyncOrchestrator(input) {
         taxonomyChangeKey: workspaceLastPushedTaxonomyChangeKeyRef.current,
         initiativeWatermarks: workspaceLastPushedInitiativeWatermarksRef.current,
         workstreamWatermarks: workspaceLastPushedWorkstreamWatermarksRef.current,
+        planningIdentityWatermarks: workspaceLastPushedPlanningIdentityWatermarksRef.current,
         aiProfileWatermarks: workspaceLastPushedAiProfileWatermarksRef.current,
         aiProfileChangeKeys: workspaceLastPushedAiProfileChangeKeysRef.current,
         taskforceAgentWatermarks: workspaceLastPushedTaskforceAgentWatermarksRef.current,
@@ -604,6 +630,9 @@ export function useSyncOrchestrator(input) {
         taxonomyStateFingerprint
     ]);
     useEffect(() => {
+        workspaceSyncGenerationRef.current += 1;
+        workspaceSyncDocumentsSnapshotCompleteRef.current = false;
+        workspaceSyncAssetsSnapshotCompleteRef.current = false;
         workspaceSyncMarkdownDocumentsFingerprintRef.current = '';
         workspaceSyncAiProfilesFingerprintRef.current = '';
         workspaceSyncAssetsFingerprintRef.current = '';
@@ -612,11 +641,15 @@ export function useSyncOrchestrator(input) {
         workspaceSyncTaskforceAgentsFingerprintRef.current = '';
         workspaceAttachBootstrapBaselineSignatureRef.current = '';
         workspaceCaptureAttachBootstrapBaselineRef.current = false;
+        workspaceSyncMarkdownDocumentsRef.current = [];
+        workspaceSyncKnownDocumentPathsRef.current = new Set();
         setWorkspaceSyncMarkdownDocuments([]);
         setWorkspaceSyncMarkdownDocumentsFingerprint('');
         workspaceSyncAiProfilesRef.current = [];
         setWorkspaceSyncAiProfiles([]);
         setWorkspaceSyncAiProfilesFingerprint('');
+        workspaceSyncAssetsRef.current = [];
+        workspaceSyncKnownAssetPathsRef.current = new Set();
         setWorkspaceSyncAssets([]);
         setWorkspaceSyncAssetsFingerprint('');
         workspaceSyncDocumentReviewSessionsRef.current = [];
@@ -648,6 +681,7 @@ export function useSyncOrchestrator(input) {
         workspaceLastPushedInitiativeWatermarksRef.current = new Map();
         workspaceLastPushedWorkstreamIdsRef.current = new Set();
         workspaceLastPushedWorkstreamWatermarksRef.current = new Map();
+        workspaceLastPushedPlanningIdentityWatermarksRef.current = new Map();
         workspaceLastPushedAiProfileIdsRef.current = new Set();
         workspaceLastPushedAiProfileWatermarksRef.current = new Map();
         workspaceLastPushedAiProfileChangeKeysRef.current = new Map();
@@ -806,6 +840,7 @@ export function useSyncOrchestrator(input) {
         lastPushedInitiativeWatermarks: workspaceLastPushedInitiativeWatermarksRef,
         lastPushedWorkstreamIds: workspaceLastPushedWorkstreamIdsRef,
         lastPushedWorkstreamWatermarks: workspaceLastPushedWorkstreamWatermarksRef,
+        lastPushedPlanningIdentityWatermarks: workspaceLastPushedPlanningIdentityWatermarksRef,
         lastPushedAiProfileIds: workspaceLastPushedAiProfileIdsRef,
         lastPushedAiProfileWatermarks: workspaceLastPushedAiProfileWatermarksRef,
         lastPushedAiProfileChangeKeys: workspaceLastPushedAiProfileChangeKeysRef,
@@ -937,6 +972,8 @@ export function useSyncOrchestrator(input) {
             assets: workspaceSyncAssetsRef.current,
             currentDocumentPaths: workspaceSyncKnownDocumentPathsRef.current,
             currentAssetPaths: workspaceSyncKnownAssetPathsRef.current,
+            documentsSnapshotComplete: workspaceSyncDocumentsSnapshotCompleteRef.current,
+            assetsSnapshotComplete: workspaceSyncAssetsSnapshotCompleteRef.current,
             documentReviewSessions: workspaceSyncDocumentReviewSessionsRef.current,
             documentReviewComments: workspaceSyncDocumentReviewCommentsRef.current,
             annotatedAttachmentSessions: workspaceSyncAnnotatedAttachmentSessionsRef.current,
@@ -961,6 +998,7 @@ export function useSyncOrchestrator(input) {
                 lastPushedInitiativeWatermarks: workspaceLastPushedInitiativeWatermarksRef.current,
                 lastPushedWorkstreamIds: workspaceLastPushedWorkstreamIdsRef.current,
                 lastPushedWorkstreamWatermarks: workspaceLastPushedWorkstreamWatermarksRef.current,
+                lastPushedPlanningIdentityWatermarks: workspaceLastPushedPlanningIdentityWatermarksRef.current,
                 lastPushedAiProfileIds: workspaceLastPushedAiProfileIdsRef.current,
                 lastPushedAiProfileWatermarks: workspaceLastPushedAiProfileWatermarksRef.current,
                 lastPushedAiProfileChangeKeys: workspaceLastPushedAiProfileChangeKeysRef.current,
@@ -1165,14 +1203,27 @@ export function useSyncOrchestrator(input) {
             return false;
         if (cloudAuthConfigured && (!authSessionResolved || !isAuthenticated))
             return false;
+        // See refreshWorkspaceSyncAssetsSnapshot for the snapshot-completeness contract
+        // this mirrors: only a response that still answers the CURRENT workspace visit
+        // may be committed or raise "ready".
+        const requestWorkspaceId = currentWorkspaceId;
+        const requestGeneration = workspaceSyncGenerationRef.current;
+        const requestSeq = (workspaceSyncDocumentsRequestSeqRef.current += 1);
+        const isStaleRequest = () => (requestWorkspaceId !== currentWorkspaceIdRef.current
+            || requestGeneration !== workspaceSyncGenerationRef.current
+            || requestSeq !== workspaceSyncDocumentsRequestSeqRef.current);
         try {
             const res = await fetch(`/api/taskforce/sync/workspace/documents?workspaceId=${encodeURIComponent(currentWorkspaceId)}`, {
                 method: 'GET',
                 credentials: 'include'
             });
+            if (isStaleRequest())
+                return false;
             if (!res.ok)
                 return false;
             const data = await res.json();
+            if (isStaleRequest())
+                return false;
             if (!Array.isArray(data?.documents))
                 return false;
             const docs = Array.isArray(data?.documents)
@@ -1201,13 +1252,18 @@ export function useSyncOrchestrator(input) {
             const fingerprint = typeof data?.fingerprint === 'string'
                 ? data.fingerprint
                 : JSON.stringify(docs.map((entry) => `${entry.path}:${entry.updatedAt}:${entry.content.length}`).sort());
-            if (fingerprint === workspaceSyncMarkdownDocumentsFingerprintRef.current)
+            if (isStaleRequest())
+                return false;
+            if (fingerprint === workspaceSyncMarkdownDocumentsFingerprintRef.current) {
+                workspaceSyncDocumentsSnapshotCompleteRef.current = true;
                 return true;
+            }
             workspaceSyncMarkdownDocumentsFingerprintRef.current = fingerprint;
             workspaceSyncMarkdownDocumentsRef.current = docs;
             workspaceSyncKnownDocumentPathsRef.current = knownDocumentPaths;
             setWorkspaceSyncMarkdownDocuments(docs);
             setWorkspaceSyncMarkdownDocumentsFingerprint(fingerprint);
+            workspaceSyncDocumentsSnapshotCompleteRef.current = true;
             return true;
         }
         catch (error) {
@@ -1218,6 +1274,12 @@ export function useSyncOrchestrator(input) {
             return false;
         }
         finally {
+            // General push readiness intentionally stays decoupled from the strict
+            // per-domain completeness contract above: a domain that's temporarily
+            // erroring must not block ALL sync forever. What must never happen is
+            // this domain's ref/deletion-completeness being treated as trustworthy
+            // off the back of a failed or stale fetch — that's guarded above, not
+            // here. See workspaceSyncDocumentsSnapshotCompleteRef.
             markWorkspaceSyncReferenceSnapshotReady('documents');
         }
     }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated, markWorkspaceSyncReferenceSnapshotReady]);
@@ -1288,14 +1350,31 @@ export function useSyncOrchestrator(input) {
             return false;
         if (cloudAuthConfigured && (!authSessionResolved || !isAuthenticated))
             return false;
+        // Snapshot-completeness contract: a response is only ever committed, and
+        // "ready" only ever raised, when it demonstrably answers the CURRENT
+        // workspace visit. Any failure, malformed payload, or response that
+        // resolves after the workspace has moved on (switched away and possibly
+        // back) is discarded outright — never coerced into "assume unchanged" or
+        // "assume empty". This is what makeWorkspaceSyncPayloadModel's delete-diff
+        // relies on via assetsSnapshotComplete.
+        const requestWorkspaceId = currentWorkspaceId;
+        const requestGeneration = workspaceSyncGenerationRef.current;
+        const requestSeq = (workspaceSyncAssetsRequestSeqRef.current += 1);
+        const isStaleRequest = () => (requestWorkspaceId !== currentWorkspaceIdRef.current
+            || requestGeneration !== workspaceSyncGenerationRef.current
+            || requestSeq !== workspaceSyncAssetsRequestSeqRef.current);
         try {
             const res = await fetch(`/api/taskforce/sync/workspace/assets?workspaceId=${encodeURIComponent(currentWorkspaceId)}`, {
                 method: 'GET',
                 credentials: 'include'
             });
+            if (isStaleRequest())
+                return false;
             if (!res.ok)
                 return false;
             const data = await res.json();
+            if (isStaleRequest())
+                return false;
             if (!Array.isArray(data?.assets))
                 return false;
             const assets = Array.isArray(data?.assets)
@@ -1328,13 +1407,18 @@ export function useSyncOrchestrator(input) {
             const fingerprint = typeof data?.fingerprint === 'string'
                 ? data.fingerprint
                 : JSON.stringify(assets.map((entry) => `${entry.path}:${entry.updatedAt}:${entry.contentBase64.length}`).sort());
-            if (fingerprint === workspaceSyncAssetsFingerprintRef.current)
+            if (isStaleRequest())
+                return false;
+            if (fingerprint === workspaceSyncAssetsFingerprintRef.current) {
+                workspaceSyncAssetsSnapshotCompleteRef.current = true;
                 return true;
+            }
             workspaceSyncAssetsFingerprintRef.current = fingerprint;
             workspaceSyncAssetsRef.current = assets;
             workspaceSyncKnownAssetPathsRef.current = knownAssetPaths;
             setWorkspaceSyncAssets(assets);
             setWorkspaceSyncAssetsFingerprint(fingerprint);
+            workspaceSyncAssetsSnapshotCompleteRef.current = true;
             return true;
         }
         catch (error) {
@@ -1345,6 +1429,8 @@ export function useSyncOrchestrator(input) {
             return false;
         }
         finally {
+            // See refreshWorkspaceSyncMarkdownDocumentsSnapshot: general push
+            // readiness stays decoupled from the strict completeness contract above.
             markWorkspaceSyncReferenceSnapshotReady('assets');
         }
     }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated, markWorkspaceSyncReferenceSnapshotReady]);
@@ -1622,6 +1708,16 @@ export function useSyncOrchestrator(input) {
         workspaceLastPushedWorkstreamWatermarksRef.current = new Map(workspaceWorkstreamsRef.current
             .map((entry) => [String(entry?.id || '').trim(), String(entry?.updatedAt || entry?.createdAt || '').trim()])
             .filter(([id]) => id.length > 0));
+        workspaceLastPushedPlanningIdentityWatermarksRef.current = new Map([
+            ...workspaceInitiativesRef.current.map((entry) => [
+                `initiative:${String(entry?.id || '').trim()}`,
+                String(entry?.identityUpdatedAt || '').trim(),
+            ]),
+            ...workspaceWorkstreamsRef.current.map((entry) => [
+                `workstream:${String(entry?.id || '').trim()}`,
+                String(entry?.identityUpdatedAt || '').trim(),
+            ]),
+        ].filter(([key, watermark]) => !key.endsWith(':') && Number.isFinite(Date.parse(watermark))));
         workspaceLastPushedAiProfileIdsRef.current = new Set(workspaceSyncAiProfilesRef.current
             .map((entry) => String(entry?.id || '').trim())
             .filter((id) => id.length > 0));
@@ -2636,6 +2732,8 @@ export function useSyncOrchestrator(input) {
             phase: localCoordinator.phase,
             snapshot: localCoordinator.snapshot,
             errorMessage: localCoordinator.error?.message || null,
+            activeCommandType: localCoordinator.activeCommandType,
+            activePriorityCommandType: localCoordinator.activePriorityCommandType,
         }
         : null;
     const switchLocalCoordinatorWorkspace = useCallback(async (targetWorkspaceId) => {
@@ -2677,6 +2775,16 @@ export function useSyncOrchestrator(input) {
         runtimeMode,
         workspaceCloudSyncEnabled,
     ]);
+    const clearLocalCoordinatorCredential = useCallback(async () => {
+        if (runtimeMode !== 'local'
+            || !localCoordinatorAttachmentEnabled)
+            return false;
+        return localCoordinator.clearCredential();
+    }, [
+        localCoordinator,
+        localCoordinatorAttachmentEnabled,
+        runtimeMode,
+    ]);
     return {
         userGlobalSyncStatus,
         setUserGlobalSyncStatus,
@@ -2700,6 +2808,7 @@ export function useSyncOrchestrator(input) {
         localCoordinatorStatus,
         switchLocalCoordinatorWorkspace,
         transferLocalCoordinatorOwnership,
+        clearLocalCoordinatorCredential,
         syncInFlightRef,
         workspaceRetryAt,
         isWorkspaceRetryPending,

package/dist/hooks/useTaskData.d.ts

@@ -1,3 +1,28 @@
+/**
+ * useTaskData
+ *
+ * Manages the task fetch lifecycle, recently-changed-task highlighting,
+ * and merge/coalesce helpers. Task and archive state arrays live in
+ * useTaskforce.ts (because they must be passed to useSyncOrchestrator),
+ * but all fetch and mutation helpers are encapsulated here.
+ *
+ * === SECTION MAP ===
+ *   === SECTION: Recently Changed ===       — recentlyChangedTaskIds, markRecentlyChangedTasks, timer cleanup
+ *   === SECTION: Fetch Functions ===        — fetchTasks, fetchArchive, refreshTaskCollections, refreshTaskCollectionsFromInvalidation
+ *   === SECTION: Revision Tracking ===      — getTaskRevisionKey, taskRevisionMapRef, hasFetchedTasksRef
+ *   === SECTION: Merge Helper ===           — mergeTaskFromServer
+ *
+ * Key return values:
+ *   - fetchTasks(isSilent?, options?) — refresh the active task list
+ *   - fetchArchive(isSilent?, options?) — refresh the archive
+ *   - refreshTaskCollections(options?) — refresh both in parallel
+ *   - refreshTaskCollectionsFromInvalidation() — scoped task collection refresh
+ *   - mergeTaskFromServer(task) — merge a single server response into both collections
+ *   - markRecentlyChangedTasks(ids) — flag task IDs for highlight animation
+ *   - recentlyChangedTaskIds — task IDs that changed in the last 2s
+ *   - getTaskRevisionKey(task) — stable revision string for change detection
+ */
+import { type MutableRefObject } from 'react';
 import type { TaskItem } from '../types';
 interface UseTaskDataProps {
     tasks: TaskItem[];
@@ -12,10 +37,19 @@ interface UseTaskDataProps {
     handleUnauthorized: () => void;
     /** Only used to detect auth changes in the fetch dependency array */
     authRequiredForApi: boolean;
+    setError?: (value: string) => void;
+    setLoading?: (value: boolean) => void;
+    pendingTaskMetadataOverlaysRef?: MutableRefObject<Map<string, PendingTaskMetadataOverlay>>;
 }
-export declare function useTaskData({ tasks, archivedTasks, setTasks, setArchivedTasks, setLoadingTasks, getCurrentWorkspaceId, workspaceResetKey, shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls, handleUnauthorized, authRequiredForApi }: UseTaskDataProps): {
+export interface PendingTaskMetadataOverlay {
+    patch: Partial<TaskItem>;
+    observedUpdatedAt: string | null;
+}
+export declare function useTaskData({ tasks, archivedTasks, setTasks, setArchivedTasks, setLoadingTasks, getCurrentWorkspaceId, workspaceResetKey, shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls, handleUnauthorized, authRequiredForApi, setError, setLoading, pendingTaskMetadataOverlaysRef, }: UseTaskDataProps): {
     tasksRef: import("react").RefObject<TaskItem[]>;
     archivedTasksRef: import("react").RefObject<TaskItem[]>;
+    taskDetails: TaskItem[];
+    staleTaskDetailRevisions: Record<string, string>;
     recentlyChangedTaskIds: string[];
     markRecentlyChangedTasks: (taskIds: string[]) => void;
     fetchTasks: (isSilent?: boolean, options?: {
@@ -26,6 +60,11 @@ export declare function useTaskData({ tasks, archivedTasks, setTasks, setArchive
     fetchArchive: (isSilent?: boolean, options?: {
         ignoreAuthGuard?: boolean;
     }) => Promise<boolean>;
+    loadTaskDetail: (task: TaskItem, options?: {
+        shouldCommit?: () => boolean;
+        force?: boolean;
+    }) => Promise<TaskItem | null>;
+    cancelTaskDetailLoad: () => void;
     refreshTaskCollections: (options?: {
         isSilent?: boolean;
         ignoreAuthGuard?: boolean;