@taskforcehq/taskforce 0.3.170 → 0.3.301

package/dist/hooks/useWorkspaceSyncController.test.js

@@ -1,236 +1,143 @@
-import { describe, it, expect, vi, afterEach } from 'vitest';
-import { renderHook, act } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
 import { useWorkspaceSyncController } from './useWorkspaceSyncController';
-vi.mock('../sync/cloudSyncApi', () => ({
-    bootstrapPushWorkspaceSnapshot: vi.fn(),
-    pullWorkspaceChanges: vi.fn(),
-    applyLocalWorkspaceChanges: vi.fn(),
-    handshakeWorkspace: vi.fn(),
-    provisionWorkspace: vi.fn()
-}));
 const makeInput = (overrides = {}) => ({
     currentWorkspaceId: 'ws-test',
-    setWorkspaceSyncReady: vi.fn(),
-    setWorkspaceCloudHydrated: vi.fn(),
     setWorkspaceCloudSyncEnabled: vi.fn(),
-    setWorkspaceSyncSourceOfTruth: vi.fn(),
-    setWorkspaceSyncOnboardingCompleted: vi.fn(),
-    setUserGlobalLastSyncedAt: vi.fn(),
+    setWorkspaceSyncPhase: vi.fn(),
     setWorkspaceLastPullAt: vi.fn(),
     setWorkspaceLastPushAt: vi.fn(),
+    setWorkspaceLastErrorMessage: vi.fn(),
     ...overrides
 });
-describe('useWorkspaceSyncController — tryAcquireWorkspacePullLease', () => {
+describe('useWorkspaceSyncController', () => {
     afterEach(() => {
         localStorage.clear();
-        vi.useRealTimers();
         vi.unstubAllGlobals();
+        vi.clearAllMocks();
     });
-    it('returns true when navigator.locks is not available (e.g. SSR or old browser)', async () => {
-        // Simulate environment without locks API
-        vi.stubGlobal('navigator', { locks: undefined });
+    it('acquires and releases a workspace sync lease', async () => {
         const { result } = renderHook(() => useWorkspaceSyncController(makeInput()));
-        let acquired;
+        let acquired = false;
         await act(async () => {
-            acquired = await result.current.tryAcquireWorkspacePullLease('ws-test');
+            acquired = await result.current.acquireWorkspaceSyncLease('ws-test', 'pull');
         });
         expect(acquired).toBe(true);
-    });
-    it('uses localStorage lease fallback and returns false when another owner holds an active lease', async () => {
-        vi.stubGlobal('navigator', { locks: undefined });
-        const leaseKey = 'taskforce.sync.pullLease.v1.ws-test';
-        window.localStorage.setItem(leaseKey, JSON.stringify({
-            owner: 'other-tab',
-            acquiredAt: Date.now(),
-            expiresAt: Date.now() + 30_000
-        }));
-        const { result } = renderHook(() => useWorkspaceSyncController(makeInput()));
-        let acquired;
-        await act(async () => {
-            acquired = await result.current.tryAcquireWorkspacePullLease('ws-test');
-        });
-        expect(acquired).toBe(false);
-    });
-    it('acquires and releases localStorage lease fallback when locks API is unavailable', async () => {
-        vi.stubGlobal('navigator', { locks: undefined });
-        const leaseKey = 'taskforce.sync.pullLease.v1.ws-test';
-        const { result } = renderHook(() => useWorkspaceSyncController(makeInput()));
-        let acquired;
-        await act(async () => {
-            acquired = await result.current.tryAcquireWorkspacePullLease('ws-test');
-        });
-        expect(acquired).toBe(true);
-        const stored = JSON.parse(String(window.localStorage.getItem(leaseKey) || '{}'));
-        expect(typeof stored.owner).toBe('string');
-        expect(Number(stored.expiresAt)).toBeGreaterThan(Date.now());
+        expect(result.current.readWorkspaceSyncLease('ws-test')?.operation).toBe('pull');
         act(() => {
-            result.current.releaseWorkspacePullLease('ws-test');
+            result.current.releaseWorkspaceSyncLease('ws-test');
         });
-        expect(window.localStorage.getItem(leaseKey)).toBeNull();
+        expect(result.current.readWorkspaceSyncLease('ws-test')).toBeNull();
     });
-    it('returns false when another tab already holds the exclusive lock (cross-tab guard)', async () => {
-        // Simulate navigator.locks.request calling the callback with null (lock unavailable)
-        const mockRequest = vi.fn().mockImplementation((_name, _opts, callback) => {
-            // ifAvailable: true — lock not available, callback receives null
-            const p = Promise.resolve(callback(null));
-            return p;
-        });
-        vi.stubGlobal('navigator', { locks: { request: mockRequest } });
+    it('refuses a healthy competing workspace sync lease owner', async () => {
+        window.localStorage.setItem('taskforce.sync.lease.v1.ws-test', JSON.stringify({
+            ownerId: 'other-window',
+            workspaceId: 'ws-test',
+            operation: 'pull',
+            heartbeatAt: new Date().toISOString(),
+            expiresAt: new Date(Date.now() + 30_000).toISOString()
+        }));
         const { result } = renderHook(() => useWorkspaceSyncController(makeInput()));
-        let acquired;
+        let acquired = true;
         await act(async () => {
-            acquired = await result.current.tryAcquireWorkspacePullLease('ws-test');
+            acquired = await result.current.acquireWorkspaceSyncLease('ws-test', 'push');
         });
         expect(acquired).toBe(false);
-        expect(mockRequest).toHaveBeenCalledOnce();
-        expect(mockRequest.mock.calls[0][0]).toBe('taskforce.sync.pullLock.ws-test');
-        expect(mockRequest.mock.calls[0][1]).toMatchObject({ mode: 'exclusive', ifAvailable: true });
+        expect(result.current.readWorkspaceSyncLease('ws-test')?.ownerId).toBe('other-window');
     });
-    it('returns true when the lock is successfully acquired', async () => {
-        // Simulate navigator.locks.request calling the callback with a lock object
-        const mockRequest = vi.fn().mockImplementation((_name, _opts, callback) => {
-            // Call callback with a fake lock object; the callback returns a never-resolving promise
-            // to "hold" the lock — we just need to verify the outer promise resolved true
-            callback({ name: _name });
-            // Return a promise that stays pending (simulating lock held)
-            return new Promise(() => { });
-        });
-        vi.stubGlobal('navigator', { locks: { request: mockRequest } });
+    it('reclaims a stale workspace sync lease owner', async () => {
+        window.localStorage.setItem('taskforce.sync.lease.v1.ws-test', JSON.stringify({
+            ownerId: 'other-window',
+            workspaceId: 'ws-test',
+            operation: 'pull',
+            heartbeatAt: '2026-03-15T10:00:00.000Z',
+            expiresAt: '2026-03-15T10:00:01.000Z'
+        }));
         const { result } = renderHook(() => useWorkspaceSyncController(makeInput()));
-        // We need a race because the lock-hold promise never resolves
-        let acquired;
+        let acquired = false;
         await act(async () => {
-            const leasePromise = result.current.tryAcquireWorkspacePullLease('ws-test');
-            // The inner Promise resolves(true) synchronously after callback is invoked
-            acquired = await leasePromise;
+            acquired = await result.current.acquireWorkspaceSyncLease('ws-test', 'repair');
         });
         expect(acquired).toBe(true);
-        expect(mockRequest).toHaveBeenCalledOnce();
-    });
-    it('returns true on second call when the lock is already held by this tab', async () => {
-        // First call acquires the lock
-        const mockRequest = vi.fn().mockImplementation((_name, _opts, callback) => {
-            callback({ name: _name });
-            return new Promise(() => { });
-        });
-        vi.stubGlobal('navigator', { locks: { request: mockRequest } });
-        const { result } = renderHook(() => useWorkspaceSyncController(makeInput()));
-        await act(async () => {
-            await result.current.tryAcquireWorkspacePullLease('ws-test');
-        });
-        // Second call should short-circuit without calling navigator.locks.request again
-        let secondAcquired;
-        await act(async () => {
-            secondAcquired = await result.current.tryAcquireWorkspacePullLease('ws-test');
-        });
-        expect(secondAcquired).toBe(true);
-        // navigator.locks.request should only have been called once (first acquisition)
-        expect(mockRequest).toHaveBeenCalledOnce();
+        expect(result.current.readWorkspaceSyncLease('ws-test')?.operation).toBe('repair');
+        expect(result.current.readWorkspaceSyncLease('ws-test')?.ownerId).not.toBe('other-window');
     });
-    it('does not treat a lock held for one workspace as acquired for another workspace', async () => {
-        const mockRequest = vi.fn()
-            .mockImplementationOnce((_name, _opts, callback) => {
-            callback({ name: _name });
-            return new Promise(() => { });
-        })
-            .mockImplementationOnce((_name, _opts, callback) => {
-            const p = Promise.resolve(callback(null));
-            return p;
-        });
-        vi.stubGlobal('navigator', { locks: { request: mockRequest } });
-        const { result } = renderHook(() => useWorkspaceSyncController(makeInput()));
-        let firstAcquired;
-        let secondAcquired;
+    it('loads legacy workspace sync state through the v2 compat mapping', async () => {
+        vi.stubGlobal('fetch', vi.fn((url) => {
+            if (url.includes('/api/taskforce/ui-state?key=workspace-sync')) {
+                return Promise.resolve({
+                    ok: true,
+                    json: () => Promise.resolve({
+                        success: true,
+                        state: {
+                            cloudSyncEnabled: true,
+                            sourceOfTruth: 'cloud',
+                            onboardingCompleted: false,
+                            pullCursor: 'cursor-1'
+                        }
+                    })
+                });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
+        }));
+        const input = makeInput();
+        const { result } = renderHook(() => useWorkspaceSyncController(input));
         await act(async () => {
-            firstAcquired = await result.current.tryAcquireWorkspacePullLease('ws-a');
-            secondAcquired = await result.current.tryAcquireWorkspacePullLease('ws-b');
+            await result.current.loadWorkspaceSyncState();
         });
-        expect(firstAcquired).toBe(true);
-        expect(secondAcquired).toBe(false);
-        expect(mockRequest).toHaveBeenCalledTimes(1);
-        expect(mockRequest.mock.calls[0][0]).toBe('taskforce.sync.pullLock.ws-a');
+        expect(input.setWorkspaceCloudSyncEnabled).toHaveBeenCalledWith(true);
+        expect(input.setWorkspaceSyncPhase).toHaveBeenCalledWith('attach-cloud');
     });
-    it('releases the lock and allows re-acquisition after releaseWorkspacePullLease', async () => {
-        let resolveHold;
-        const mockRequest = vi.fn().mockImplementation((_name, _opts, callback) => {
-            callback({ name: _name });
-            return new Promise((resolve) => { resolveHold = resolve; });
-        });
-        vi.stubGlobal('navigator', { locks: { request: mockRequest } });
-        const { result } = renderHook(() => useWorkspaceSyncController(makeInput()));
-        await act(async () => {
-            await result.current.tryAcquireWorkspacePullLease('ws-test');
-        });
-        // Release the lock
-        act(() => {
-            result.current.releaseWorkspacePullLease('ws-test');
-            resolveHold(); // allow the lock-hold promise to settle
-        });
-        // Now try to acquire again — should call navigator.locks.request a second time
+    it('persists attach-cloud phase when enabling sync for an existing cloud workspace', async () => {
+        const uiStatePosts = [];
+        vi.stubGlobal('fetch', vi.fn((url, init) => {
+            if (url.includes('/api/taskforce/ui-state') && String(init?.method || '').toUpperCase() === 'POST') {
+                uiStatePosts.push(JSON.parse(String(init?.body || '{}')));
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
+        }));
+        const input = makeInput();
+        const { result } = renderHook(() => useWorkspaceSyncController(input));
+        let saveResult;
         await act(async () => {
-            await result.current.tryAcquireWorkspacePullLease('ws-test');
-        });
-        expect(mockRequest).toHaveBeenCalledTimes(2);
-    });
-    it('resets in-flight push/pull refs when workspace changes', async () => {
-        let input = makeInput({ currentWorkspaceId: 'ws-a' });
-        const { result, rerender } = renderHook((props) => useWorkspaceSyncController(props), {
-            initialProps: input
-        });
-        act(() => {
-            result.current.workspacePushInFlightRef.current = true;
-            result.current.workspacePullInFlightRef.current = true;
-        });
-        input = makeInput({ currentWorkspaceId: 'ws-b' });
-        rerender(input);
-        expect(result.current.workspacePushInFlightRef.current).toBe(false);
-        expect(result.current.workspacePullInFlightRef.current).toBe(false);
+            saveResult = await result.current.saveWorkspaceCloudSyncSettings({ enabled: true }, {
+                cloudAuthConfigured: true,
+                isAuthenticated: true,
+                ensureCloudWorkspaceReadyForSync: async () => ({ success: true, provisioned: false })
+            });
+        });
+        expect(saveResult).toEqual({ success: true });
+        expect(input.setWorkspaceCloudSyncEnabled).toHaveBeenCalledWith(true);
+        expect(input.setWorkspaceSyncPhase).toHaveBeenCalledWith('attach-cloud');
+        expect(uiStatePosts.some((entry) => entry?.patch?.version === 2
+            && entry?.patch?.enabled === true
+            && entry?.patch?.phase === 'attach-cloud'
+            && entry?.patch?.pullCursor === null)).toBe(true);
     });
-    it('clears same-deadline cooldown when retry timer fires so scheduled pull is not self-blocked', async () => {
-        const { result } = renderHook(() => useWorkspaceSyncController(makeInput({ currentWorkspaceId: 'ws-cooldown' })));
-        const invokePull = vi.fn().mockResolvedValue(true);
-        let scheduledRetryCallback = null;
-        const setTimeoutSpy = vi.spyOn(window, 'setTimeout').mockImplementation(((callback) => {
-            scheduledRetryCallback = callback;
-            return 1;
+    it('persists provision-local phase when enabling sync for a new cloud workspace', async () => {
+        const uiStatePosts = [];
+        vi.stubGlobal('fetch', vi.fn((url, init) => {
+            if (url.includes('/api/taskforce/ui-state') && String(init?.method || '').toUpperCase() === 'POST') {
+                uiStatePosts.push(JSON.parse(String(init?.body || '{}')));
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
         }));
-        const clearTimeoutSpy = vi.spyOn(window, 'clearTimeout').mockImplementation((() => { }));
-        act(() => {
-            result.current.scheduleWorkspacePullRetry(invokePull, { minDelayMs: 250, workspaceId: 'ws-cooldown' });
-        });
-        const cooldownKey = 'taskforce.sync.pullCooldown.v1.ws-cooldown';
-        const before = JSON.parse(String(window.localStorage.getItem(cooldownKey) || '{}'));
-        expect(Number(before.nextAllowedAt)).toBeGreaterThan(Date.now());
-        expect(typeof scheduledRetryCallback).toBe('function');
-        act(() => {
-            scheduledRetryCallback?.();
-        });
-        expect(invokePull).toHaveBeenCalledTimes(1);
-        const after = JSON.parse(String(window.localStorage.getItem(cooldownKey) || '{}'));
-        expect(Number(after.nextAllowedAt)).toBeLessThanOrEqual(Date.now());
-        expect(result.current.isWorkspacePullCooldownActive('ws-cooldown')).toBe(false);
-        setTimeoutSpy.mockRestore();
-        clearTimeoutSpy.mockRestore();
-    });
-    it('keeps recordWorkspaceSyncFailure stable and dispatches to latest onFailureRecorded callback', () => {
-        const firstCallback = vi.fn();
-        let input = makeInput({ onFailureRecorded: firstCallback });
-        const { result, rerender } = renderHook((props) => useWorkspaceSyncController(props), {
-            initialProps: input
-        });
-        const recordBeforeRerender = result.current.recordWorkspaceSyncFailure;
-        act(() => {
-            result.current.recordWorkspaceSyncFailure('pull', 503);
-        });
-        expect(firstCallback).toHaveBeenCalledWith('pull', 503);
-        const secondCallback = vi.fn();
-        input = makeInput({ onFailureRecorded: secondCallback });
-        rerender(input);
-        const recordAfterRerender = result.current.recordWorkspaceSyncFailure;
-        expect(recordAfterRerender).toBe(recordBeforeRerender);
-        act(() => {
-            result.current.recordWorkspaceSyncFailure('handshake', 429);
-        });
-        expect(secondCallback).toHaveBeenCalledWith('handshake', 429);
+        const input = makeInput();
+        const { result } = renderHook(() => useWorkspaceSyncController(input));
+        let saveResult;
+        await act(async () => {
+            saveResult = await result.current.saveWorkspaceCloudSyncSettings({ enabled: true }, {
+                cloudAuthConfigured: true,
+                isAuthenticated: true,
+                ensureCloudWorkspaceReadyForSync: async () => ({ success: true, provisioned: true })
+            });
+        });
+        expect(saveResult).toEqual({ success: true });
+        expect(input.setWorkspaceSyncPhase).toHaveBeenCalledWith('provision-local');
+        expect(uiStatePosts.some((entry) => entry?.patch?.version === 2
+            && entry?.patch?.enabled === true
+            && entry?.patch?.phase === 'provision-local')).toBe(true);
     });
 });

package/dist/hooks/workspace/useTaskforceApiRouting.d.ts

@@ -0,0 +1,8 @@
+import { type MutableRefObject } from 'react';
+interface UseTaskforceApiRoutingInput {
+    currentWorkspaceIdRef: MutableRefObject<string>;
+    resolveApiUrl: (path: string) => string;
+    runtimeMode: 'local' | 'cloud';
+}
+export declare function useTaskforceApiRouting({ currentWorkspaceIdRef, resolveApiUrl, runtimeMode }: UseTaskforceApiRoutingInput): void;
+export {};

package/dist/hooks/workspace/useTaskforceApiRouting.js

@@ -0,0 +1,91 @@
+import { useEffect } from 'react';
+function isLocalOnlyTaskforcePath(pathname) {
+    return pathname === '/api/taskforce/auth/runtime-config'
+        || pathname === '/api/taskforce/sync/workspace/apply-local'
+        || pathname === '/api/taskforce/sync/workspace/repair-startup';
+}
+function resolveInputUrl(input) {
+    try {
+        if (typeof window === 'undefined')
+            return null;
+        if (typeof input === 'string')
+            return new URL(input, window.location.origin);
+        if (input instanceof URL)
+            return input;
+        if (typeof Request !== 'undefined' && input instanceof Request) {
+            return new URL(input.url, window.location.origin);
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function useTaskforceApiRouting({ currentWorkspaceIdRef, resolveApiUrl, runtimeMode }) {
+    useEffect(() => {
+        if (typeof window === 'undefined' || typeof window.fetch !== 'function')
+            return;
+        const originalFetch = window.fetch.bind(window);
+        const rewriteTaskforceApiRequest = (input) => {
+            if (typeof input === 'string') {
+                if (runtimeMode !== 'cloud')
+                    return input;
+                return (input.startsWith('/api/taskforce') && !isLocalOnlyTaskforcePath(input)) ? resolveApiUrl(input) : input;
+            }
+            if (input instanceof URL) {
+                if (runtimeMode !== 'cloud')
+                    return input;
+                if (input.origin === window.location.origin && input.pathname.startsWith('/api/taskforce')) {
+                    if (isLocalOnlyTaskforcePath(input.pathname))
+                        return input;
+                    return new URL(resolveApiUrl(`${input.pathname}${input.search}${input.hash}`));
+                }
+                return input;
+            }
+            if (typeof Request !== 'undefined' && input instanceof Request) {
+                if (runtimeMode !== 'cloud')
+                    return input;
+                const parsed = new URL(input.url, window.location.origin);
+                if (parsed.origin === window.location.origin && parsed.pathname.startsWith('/api/taskforce')) {
+                    if (isLocalOnlyTaskforcePath(parsed.pathname))
+                        return input;
+                    return resolveApiUrl(`${parsed.pathname}${parsed.search}${parsed.hash}`);
+                }
+            }
+            return input;
+        };
+        window.fetch = ((input, init) => {
+            const nextInput = rewriteTaskforceApiRequest(input);
+            const resolvedUrl = resolveInputUrl(nextInput);
+            const shouldInjectWorkspaceHeader = Boolean(resolvedUrl
+                && resolvedUrl.pathname.startsWith('/api/taskforce')
+                && !isLocalOnlyTaskforcePath(resolvedUrl.pathname));
+            if (!shouldInjectWorkspaceHeader) {
+                return originalFetch(nextInput, init);
+            }
+            const workspaceIdHeader = String(currentWorkspaceIdRef.current || '').trim();
+            if (typeof Request !== 'undefined' && nextInput instanceof Request) {
+                const headers = new Headers(nextInput.headers);
+                if (init?.headers) {
+                    const initHeaders = new Headers(init.headers);
+                    initHeaders.forEach((value, key) => headers.set(key, value));
+                }
+                if (workspaceIdHeader && workspaceIdHeader !== 'default' && !headers.has('x-taskforce-workspace-id')) {
+                    headers.set('x-taskforce-workspace-id', workspaceIdHeader);
+                    headers.set('x-taskforce-workspace-authoritative', '1');
+                }
+                const request = new Request(nextInput, { ...init, headers });
+                return originalFetch(request);
+            }
+            const headers = new Headers(init?.headers);
+            if (workspaceIdHeader && workspaceIdHeader !== 'default' && !headers.has('x-taskforce-workspace-id')) {
+                headers.set('x-taskforce-workspace-id', workspaceIdHeader);
+                headers.set('x-taskforce-workspace-authoritative', '1');
+            }
+            return originalFetch(nextInput, { ...init, headers });
+        });
+        return () => {
+            window.fetch = originalFetch;
+        };
+    }, [currentWorkspaceIdRef, resolveApiUrl, runtimeMode]);
+}

package/dist/hooks/workspace/useTaskforceApiRouting.test.d.ts

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

package/dist/hooks/workspace/useTaskforceApiRouting.test.js

@@ -0,0 +1,60 @@
+import { renderHook } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createRef } from 'react';
+import { useTaskforceApiRouting } from './useTaskforceApiRouting';
+describe('useTaskforceApiRouting', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('keeps local-only sync routes on the current origin in cloud runtime', async () => {
+        const fetchMock = vi.fn(async (input) => new Response(null, { status: 204 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const currentWorkspaceIdRef = createRef();
+        currentWorkspaceIdRef.current = 'workspace-1';
+        renderHook(() => useTaskforceApiRouting({
+            currentWorkspaceIdRef,
+            runtimeMode: 'cloud',
+            resolveApiUrl: (path) => `https://cloud.example.com${path}`
+        }));
+        await window.fetch('/api/taskforce/sync/workspace/repair-startup', { method: 'POST' });
+        await window.fetch('/api/taskforce/sync/workspace/apply-local', { method: 'POST' });
+        await window.fetch('/api/taskforce/auth/runtime-config');
+        expect(fetchMock.mock.calls.map(([input]) => String(input))).toEqual([
+            '/api/taskforce/sync/workspace/repair-startup',
+            '/api/taskforce/sync/workspace/apply-local',
+            '/api/taskforce/auth/runtime-config'
+        ]);
+    });
+    it('still rewrites cloud-owned taskforce routes in cloud runtime', async () => {
+        const fetchMock = vi.fn(async (input) => new Response(null, { status: 204 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const currentWorkspaceIdRef = createRef();
+        currentWorkspaceIdRef.current = 'workspace-1';
+        renderHook(() => useTaskforceApiRouting({
+            currentWorkspaceIdRef,
+            runtimeMode: 'cloud',
+            resolveApiUrl: (path) => `https://cloud.example.com${path}`
+        }));
+        await window.fetch('/api/taskforce/sync/workspace/pull?workspaceId=workspace-1');
+        expect(fetchMock).toHaveBeenCalledWith('https://cloud.example.com/api/taskforce/sync/workspace/pull?workspaceId=workspace-1', expect.objectContaining({
+            headers: expect.any(Headers)
+        }));
+    });
+    it('reads the injected workspace header from the live ref without waiting for rerender', async () => {
+        const fetchMock = vi.fn(async (_input, init) => new Response(null, { status: 204 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const currentWorkspaceIdRef = createRef();
+        currentWorkspaceIdRef.current = 'workspace-1';
+        renderHook(() => useTaskforceApiRouting({
+            currentWorkspaceIdRef,
+            runtimeMode: 'cloud',
+            resolveApiUrl: (path) => `https://cloud.example.com${path}`
+        }));
+        currentWorkspaceIdRef.current = 'workspace-2';
+        await window.fetch('/api/taskforce/tasks');
+        const [, init] = fetchMock.mock.calls.at(-1);
+        const headers = init.headers;
+        expect(headers.get('x-taskforce-workspace-id')).toBe('workspace-2');
+        expect(headers.get('x-taskforce-workspace-authoritative')).toBe('1');
+    });
+});

package/dist/hooks/workspace/useWorkspaceSyncController.d.ts

@@ -0,0 +1 @@
+export { useWorkspaceSyncController } from '../useWorkspaceSyncController';

package/dist/hooks/workspace/useWorkspaceSyncController.js

@@ -0,0 +1 @@
+export { useWorkspaceSyncController } from '../useWorkspaceSyncController';

package/dist/hooks/workspace/workspaceLocalState.d.ts

@@ -0,0 +1,30 @@
+import type { TaskAssignee } from '../../types';
+import type { TaskSortKey } from '../../utils/taxonomySorting.js';
+export interface PersistedUiState {
+    groupBy?: 'category' | 'type' | 'priority' | 'approach' | 'assignee' | 'status' | 'complexity' | 'schedule' | 'docs';
+    activeWorkspaceModule?: 'tasks' | 'docs' | 'annotate' | 'workflows' | 'agents';
+    emptyColumnMode?: 'show' | 'collapse' | 'hide';
+    zenMode?: boolean;
+    searchQuery?: string;
+    filterCategories?: string[];
+    filterPriorities?: (string | number)[];
+    filterTypes?: string[];
+    filterStatus?: (string | number)[];
+    filterAssignees?: TaskAssignee[];
+    filterAssigneesAllSelected?: boolean;
+    filterTaxonomies?: Record<string, (string | number)[]>;
+    sortBy?: TaskSortKey;
+    sortOrder?: 'asc' | 'desc';
+    hasInitedFilters?: boolean;
+    showChecklist?: boolean;
+    showWorkstreamSection?: boolean;
+    showTaskRelationships?: boolean;
+    lastCategory?: string;
+    exportEnvironment?: string;
+}
+export declare function generateClientUuid(): string;
+export declare function logBootstrapDebug(event: string, details?: Record<string, unknown>): void;
+export declare function readPersistedWorkspaceId(scopeRaw?: string): string;
+export declare function writePersistedWorkspaceId(workspaceId: string, scopeRaw?: string): void;
+export declare function readPersistedAppUiState(scopeRaw?: string): PersistedUiState | null;
+export declare function writePersistedAppUiState(state: PersistedUiState, scopeRaw?: string): void;