@taskforcehq/taskforce 0.3.304 → 0.3.306

package/dist/sync/syncApplyHandlers.test.js

@@ -1,4 +1,6 @@
-import { describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { describe, expect, it, vi, afterEach } from 'vitest';
 import { applyCollaborationSyncChanges, applyContentSyncChanges, applyPreparedTaskSyncSnapshot, applyTaskSyncDeletes, classifyWorkspaceSyncChanges, prepareTaskSyncSnapshotApply, } from './syncApplyHandlers.js';
 function createCoreFixture(overrides = {}) {
     return {
@@ -29,6 +31,9 @@ function createCoreFixture(overrides = {}) {
     };
 }
 describe('syncApplyHandlers', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
     it('classifies task and workstream changes, then prepares and applies the task snapshot pipeline', () => {
         const diagnostics = [];
         const workspaceId = 'workspace-1';
@@ -76,15 +81,18 @@ describe('syncApplyHandlers', () => {
                 {
                     op: 'delete',
                     taskId: 'task-1',
+                    deletedAt: '2026-04-10T11:00:00.000Z',
                 },
                 {
                     op: 'delete',
                     taskId: 'task-stale',
+                    deletedAt: '2026-04-10T08:00:00.000Z',
                 },
             ],
             normalizeWorkspaceSyncDocumentPath: (rawPath) => typeof rawPath === 'string' ? rawPath : null,
             normalizeTaskAssetPath: (rawPath) => typeof rawPath === 'string' ? rawPath : null,
             normalizeIncomingAiProfileSurfaceType: () => null,
+            normalizeIncomingAiProfileSeatScope: () => null,
             normalizeTaskEventSyncPayload: () => null,
             recordSyncDiagnostic: (targetWorkspaceId, eventType, message, details) => {
                 diagnostics.push({ workspaceId: targetWorkspaceId, eventType, message, details });
@@ -229,7 +237,7 @@ describe('syncApplyHandlers', () => {
         expect(core.notifyDocumentMetadataMutation).toHaveBeenNthCalledWith(1, 'workspace-1', ['docs/spec.md', 'assets/proof.png'], 'upsert');
         expect(core.notifyDocumentMetadataMutation).toHaveBeenNthCalledWith(2, 'workspace-1', ['docs/stale.md', 'assets/stale.png'], 'delete');
     });
-    it('only allows reference reassignment for content writes when the content changed or repair is explicit', async () => {
+    it('allows reference reassignment when metadata drift requires normal sync convergence', async () => {
         const core = createCoreFixture({
             getDocumentWatermark: vi.fn().mockReturnValue(null),
         });
@@ -278,9 +286,70 @@ describe('syncApplyHandlers', () => {
             }),
             recordSyncDiagnostic: vi.fn(),
         });
-        expect(writeWorkspaceSyncDocument).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'docs/spec.md' }), 'workspace-1', { allowReferenceNumberReassignment: false });
+        expect(writeWorkspaceSyncDocument).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'docs/spec.md' }), 'workspace-1', { allowReferenceNumberReassignment: true });
         expect(writeWorkspaceSyncBinaryAsset).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'assets/proof.png' }), 'workspace-1', { allowReferenceNumberReassignment: true });
     });
+    it('reuses persisted content hashes instead of re-reading unchanged local files', async () => {
+        const existingDocContent = '# Spec';
+        const existingAssetBytes = Buffer.from('png-bytes');
+        const core = createCoreFixture({
+            getDocumentWatermark: vi.fn().mockReturnValue({
+                updatedAt: '2026-04-10T10:00:00.000Z',
+                contentHash: createHash('sha256').update(existingDocContent).digest('hex'),
+            }),
+        });
+        const writeWorkspaceSyncDocument = vi.fn().mockResolvedValue(undefined);
+        const writeWorkspaceSyncBinaryAsset = vi.fn().mockResolvedValue(undefined);
+        const readSpy = vi.spyOn(fs, 'readFileSync').mockImplementation(((targetPath) => {
+            const value = String(targetPath);
+            if (value.endsWith('spec.md'))
+                return existingDocContent;
+            return existingAssetBytes;
+        }));
+        await applyContentSyncChanges({
+            core,
+            workspaceId: 'workspace-1',
+            incomingDocuments: [
+                {
+                    path: 'docs/spec.md',
+                    updatedAt: '2026-04-10T10:00:00.000Z',
+                    content: existingDocContent,
+                    assetId: 'asset-doc-1',
+                },
+            ],
+            incomingDocumentDeletes: new Map(),
+            incomingAssets: [
+                {
+                    path: 'assets/proof.png',
+                    updatedAt: '2026-04-10T10:05:00.000Z',
+                    contentBase64: existingAssetBytes.toString('base64'),
+                    assetId: 'asset-image-1',
+                    kind: 'image',
+                    mimeType: 'image/png',
+                },
+            ],
+            incomingAssetDeletes: new Map(),
+            basePath: '/tmp/taskforce-sync-content',
+            hasObjectStorageClient: () => true,
+            hasDocumentSyncMetadataDrift: () => false,
+            hasBinaryAssetSyncMetadataDrift: () => false,
+            getExistingDocument: () => {
+                throw new Error('document fallback should not be used when persisted metadata exists');
+            },
+            writeWorkspaceSyncDocument,
+            deleteWorkspaceSyncDocument: vi.fn(),
+            writeWorkspaceSyncBinaryAsset,
+            deleteWorkspaceSyncBinaryAsset: vi.fn(),
+            getExistingBinaryAsset: () => ({
+                updatedAt: '2026-04-10T10:05:00.000Z',
+                contentSha256: createHash('sha256').update(existingAssetBytes).digest('hex'),
+            }),
+            recordSyncDiagnostic: vi.fn(),
+        });
+        expect(readSpy).not.toHaveBeenCalled();
+        expect(writeWorkspaceSyncDocument).not.toHaveBeenCalled();
+        expect(writeWorkspaceSyncBinaryAsset).not.toHaveBeenCalled();
+    });
     it('applies collaboration upserts and deletes through the collaboration handlers', () => {
         const core = createCoreFixture();
         applyCollaborationSyncChanges({

package/dist/sync/syncFieldSemantics.d.ts

@@ -0,0 +1,12 @@
+export declare function hasOwnSyncField(source: unknown, field: string): boolean;
+export declare function normalizeSyncOptionalString(value: unknown): string | undefined;
+export declare function normalizeSyncNullableString(value: unknown): string | null;
+export declare function normalizeSyncOptionalId(value: unknown): string | undefined;
+export declare function normalizeSyncNullableId(value: unknown): string | null;
+export declare function normalizeSyncNullableIsoString(value: unknown): string | null;
+export declare function normalizeSyncSameOriginAssetUrl(value: unknown): string | null;
+export declare function readSyncOptionalStringField(source: Record<string, unknown>, field: string): string | undefined;
+export declare function readSyncNullableStringField(source: Record<string, unknown>, field: string): string | null | undefined;
+export declare function readSyncNullableIdField(source: Record<string, unknown>, field: string): string | null | undefined;
+export declare function readSyncNullableIsoStringField(source: Record<string, unknown>, field: string): string | null | undefined;
+export declare function readSyncSameOriginAssetUrlField(source: Record<string, unknown>, field: string): string | null | undefined;

package/dist/sync/syncFieldSemantics.js

@@ -0,0 +1,55 @@
+export function hasOwnSyncField(source, field) {
+    return Boolean(source) && typeof source === 'object' && Object.prototype.hasOwnProperty.call(source, field);
+}
+export function normalizeSyncOptionalString(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const normalized = String(value).trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+export function normalizeSyncNullableString(value) {
+    if (value === undefined || value === null)
+        return null;
+    const normalized = String(value).trim();
+    return normalized.length > 0 ? normalized : null;
+}
+export function normalizeSyncOptionalId(value) {
+    return normalizeSyncOptionalString(value);
+}
+export function normalizeSyncNullableId(value) {
+    return normalizeSyncNullableString(value);
+}
+export function normalizeSyncNullableIsoString(value) {
+    return normalizeSyncNullableString(value);
+}
+export function normalizeSyncSameOriginAssetUrl(value) {
+    const normalized = normalizeSyncNullableString(value);
+    if (!normalized)
+        return null;
+    return normalized.startsWith('/api/taskforce/context/') ? normalized : null;
+}
+export function readSyncOptionalStringField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncOptionalString(source[field]);
+}
+export function readSyncNullableStringField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncNullableString(source[field]);
+}
+export function readSyncNullableIdField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncNullableId(source[field]);
+}
+export function readSyncNullableIsoStringField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncNullableIsoString(source[field]);
+}
+export function readSyncSameOriginAssetUrlField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncSameOriginAssetUrl(source[field]);
+}

package/dist/sync/syncResourceAdapters.d.ts

@@ -0,0 +1,44 @@
+import type { TaskItem } from '../types.js';
+export interface SyncAiProfileLike {
+    id?: string | null;
+    workspaceId?: string | null;
+    profileToken?: string | null;
+    name?: string | null;
+    username?: string | null;
+    icon?: string | null;
+    color?: string | null;
+    avatarUrl?: string | null;
+    avatarSourceUrl?: string | null;
+    description?: string | null;
+    role?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    surfaceType?: string | null;
+    seatScope?: string | null;
+    providerMetadata?: Record<string, unknown> | null;
+    archivedAt?: string | null;
+    archivedBy?: string | null;
+    archivedReason?: string | null;
+    mergedIntoProfileId?: string | null;
+    rosterStateUpdatedAt?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    lastActiveAt?: string | null;
+}
+export interface SyncResourceAdapter<T> {
+    kind: string;
+    getId: (resource: T) => string;
+    getWatermark: (resource: T) => string;
+    getChangeKey: (resource: T) => string;
+}
+export interface SyncResourceBaselineState {
+    watermarks?: Map<string, string> | null;
+    changeKeys?: Map<string, string> | null;
+}
+export declare function getAiProfileSyncWatermark(profile: Partial<SyncAiProfileLike> | null | undefined): string;
+export declare function getAiProfileSyncChangeKey(profile: Partial<SyncAiProfileLike> | null | undefined): string;
+export declare const taskSyncResourceAdapter: SyncResourceAdapter<Partial<TaskItem> & {
+    isArchived?: boolean | null;
+}>;
+export declare const aiProfileSyncResourceAdapter: SyncResourceAdapter<Partial<SyncAiProfileLike>>;
+export declare function shouldSyncResource<T>(adapter: SyncResourceAdapter<T>, resource: T, baseline?: SyncResourceBaselineState | null): boolean;

package/dist/sync/syncResourceAdapters.js

@@ -0,0 +1,77 @@
+import { buildTaskSyncChangeKey } from './taskSyncChangeKey.js';
+import { normalizeSyncNullableIsoString, normalizeSyncNullableString, normalizeSyncOptionalId, normalizeSyncSameOriginAssetUrl, } from './syncFieldSemantics.js';
+function normalizeSyncTimestampMax(...values) {
+    return values.reduce((latest, value) => {
+        const normalized = normalizeSyncNullableIsoString(value) || '';
+        if (!latest)
+            return normalized;
+        if (!normalized)
+            return latest;
+        return normalized > latest ? normalized : latest;
+    }, '');
+}
+export function getAiProfileSyncWatermark(profile) {
+    const source = profile || {};
+    return normalizeSyncTimestampMax(source.createdAt, source.updatedAt, source.lastActiveAt, source.archivedAt, source.rosterStateUpdatedAt);
+}
+export function getAiProfileSyncChangeKey(profile) {
+    const source = profile || {};
+    return JSON.stringify({
+        id: String(source.id || '').trim(),
+        workspaceId: String(source.workspaceId || '').trim(),
+        profileToken: String(source.profileToken || '').trim(),
+        name: String(source.name || '').trim(),
+        username: String(source.username || '').trim(),
+        icon: String(source.icon || 'Bot').trim() || 'Bot',
+        color: String(source.color || '#8b5cf6').trim() || '#8b5cf6',
+        avatarUrl: normalizeSyncSameOriginAssetUrl(source.avatarUrl) || '',
+        avatarSourceUrl: normalizeSyncSameOriginAssetUrl(source.avatarSourceUrl) || '',
+        description: normalizeSyncNullableString(source.description) || '',
+        role: normalizeSyncNullableString(source.role) || '',
+        provider: normalizeSyncNullableString(source.provider) || '',
+        model: normalizeSyncNullableString(source.model) || '',
+        surfaceType: normalizeSyncNullableString(source.surfaceType) || '',
+        seatScope: normalizeSyncNullableString(source.seatScope) || '',
+        providerMetadata: source.providerMetadata && typeof source.providerMetadata === 'object' && !Array.isArray(source.providerMetadata)
+            ? source.providerMetadata
+            : null,
+        archivedAt: normalizeSyncNullableIsoString(source.archivedAt) || '',
+        archivedBy: normalizeSyncOptionalId(source.archivedBy) || '',
+        archivedReason: normalizeSyncNullableString(source.archivedReason) || '',
+        mergedIntoProfileId: normalizeSyncOptionalId(source.mergedIntoProfileId) || '',
+        rosterStateUpdatedAt: normalizeSyncNullableIsoString(source.rosterStateUpdatedAt) || '',
+        createdAt: normalizeSyncNullableIsoString(source.createdAt) || '',
+        updatedAt: normalizeSyncNullableIsoString(source.updatedAt) || '',
+        lastActiveAt: normalizeSyncNullableIsoString(source.lastActiveAt) || '',
+    });
+}
+export const taskSyncResourceAdapter = {
+    kind: 'task',
+    getId: (task) => String(task?.id || '').trim(),
+    getWatermark: (task) => String(task?.updatedAt || task?.createdAt || '').trim(),
+    getChangeKey: (task) => buildTaskSyncChangeKey(task, Boolean(task?.isArchived))
+};
+export const aiProfileSyncResourceAdapter = {
+    kind: 'ai-profile',
+    getId: (profile) => String(profile?.id || '').trim(),
+    getWatermark: (profile) => getAiProfileSyncWatermark(profile),
+    getChangeKey: (profile) => getAiProfileSyncChangeKey(profile)
+};
+export function shouldSyncResource(adapter, resource, baseline) {
+    const id = adapter.getId(resource);
+    if (!id)
+        return false;
+    const currentChangeKey = adapter.getChangeKey(resource);
+    const previousWatermarks = baseline?.watermarks;
+    if (!previousWatermarks || previousWatermarks.size === 0)
+        return true;
+    if (!previousWatermarks.has(id))
+        return true;
+    const previousChangeKeys = baseline?.changeKeys;
+    const previousChangeKey = previousChangeKeys?.get(id);
+    if (typeof previousChangeKey === 'string') {
+        return previousChangeKey !== currentChangeKey;
+    }
+    const previousWatermark = previousWatermarks.get(id) || '';
+    return previousWatermark !== currentChangeKey;
+}

package/dist/sync/syncService.d.ts

@@ -7,6 +7,7 @@ export interface EnsureWorkspaceReadyInput {
     resolveCloudAuthUrl: (path: string) => string;
     workspaceId: string;
     workspaceName: string;
+    allowProvisionOnMismatch?: boolean;
 }
 export interface EnsureWorkspaceReadyResult {
     success: boolean;
@@ -55,6 +56,8 @@ export interface WorkspacePushSyncResult {
     changeCount: number;
     deleteCount: number;
     currentTaskIds: Set<string>;
+    currentTaskWatermarks?: Map<string, string>;
+    currentTaskChangeKeys?: Map<string, string>;
     deleteTaskIds: Set<string>;
     currentInitiativeIds: Set<string>;
     currentInitiativeWatermarks: Map<string, string>;
@@ -62,6 +65,7 @@ export interface WorkspacePushSyncResult {
     currentWorkstreamWatermarks: Map<string, string>;
     currentAiProfileIds: Set<string>;
     currentAiProfileWatermarks: Map<string, string>;
+    currentAiProfileChangeKeys?: Map<string, string>;
     currentDocumentPaths: Set<string>;
     deleteDocumentPaths: Set<string>;
     currentDocumentWatermarks: Map<string, string>;
@@ -80,6 +84,7 @@ export interface WorkspacePushSyncResult {
     currentTaskEventWatermarks: Map<string, string>;
     /** Watermarks for every task upsert that was successfully pushed. */
     pushedWatermarks: Map<string, string>;
+    pushedTaskChangeKeys?: Map<string, string>;
     /** Server-emitted realtime mutation event ids for this push apply. */
     emittedEventIds: string[];
     /** Authoritative task snapshots returned immediately by the push route for incoming task upserts. */
@@ -105,6 +110,7 @@ export interface WorkspacePullSyncResult {
     success: boolean;
     kind?: WorkspacePullFailureKind;
     status?: number;
+    errorCode?: string;
     retryAfterMs?: number;
     transient?: boolean;
     failures?: string[];

package/dist/sync/syncService.js

@@ -15,6 +15,14 @@ function resolveWorkspaceAccessConflictMessage(data, fallbackStatus) {
     }
     return rawError || `Workspace provisioning failed (${fallbackStatus})`;
 }
+function isMissingCloudWorkspaceSelection(data, status) {
+    if (status !== 400)
+        return false;
+    const code = String(data.code || '').trim().toUpperCase();
+    const rawError = String(data.error || '').trim().toLowerCase();
+    return code === 'WORKSPACE_ID_REQUIRED'
+        && rawError.includes('no cloud workspace is selected');
+}
 export async function ensureCloudWorkspaceReadyForSyncService(input) {
     if (!input.cloudAuthConfigured)
         return { success: false, error: 'Cloud auth endpoint is not configured.' };
@@ -44,7 +52,48 @@ export async function ensureCloudWorkspaceReadyForSyncService(input) {
                 error: String(data.error || 'Workspace sync rate limited. Please retry later.')
             };
         }
+        if (isMissingCloudWorkspaceSelection(data, handshakeResult.status)) {
+            const provisionResult = await provisionWorkspace(input.resolveCloudAuthUrl, {
+                workspaceId: input.workspaceId,
+                name: input.workspaceName || input.workspaceId
+            });
+            if (!provisionResult.ok) {
+                const provisionError = asObjectRecord(provisionResult.data);
+                return {
+                    success: false,
+                    statusCode: provisionResult.status,
+                    transient: isTransientWorkspaceSyncStatus(provisionResult.status),
+                    retryAfterMs: provisionResult.retryAfterMs,
+                    error: resolveWorkspaceAccessConflictMessage(provisionError, provisionResult.status)
+                };
+            }
+            handshakeResult = await handshakeWorkspace(input.resolveCloudAuthUrl, input.workspaceId);
+            if (!handshakeResult.ok) {
+                const retryData = asObjectRecord(handshakeResult.data);
+                if (handshakeResult.status === 401) {
+                    return { success: false, statusCode: 401, transient: false, error: String(retryData.error || 'Authentication required for workspace sync.') };
+                }
+                if (handshakeResult.status === 429) {
+                    return { success: false, statusCode: 429, retryAfterMs: handshakeResult.retryAfterMs, transient: true, error: String(retryData.error || 'Workspace sync rate limited. Please retry later.') };
+                }
+                return {
+                    success: false,
+                    statusCode: handshakeResult.status,
+                    transient: isTransientWorkspaceSyncStatus(handshakeResult.status),
+                    error: String(retryData.error || `Workspace sync handshake failed (${handshakeResult.status})`)
+                };
+            }
+            return { success: true, provisioned: true };
+        }
         if (handshakeResult.status === 409 && data.code === 'WORKSPACE_ID_MISMATCH') {
+            if (input.allowProvisionOnMismatch === false) {
+                return {
+                    success: false,
+                    statusCode: 409,
+                    transient: false,
+                    error: String(data.error || 'Selected cloud workspace could not be attached to this local workspace.')
+                };
+            }
             const provisionResult = await provisionWorkspace(input.resolveCloudAuthUrl, {
                 workspaceId: input.workspaceId,
                 name: input.workspaceName || input.workspaceId
@@ -165,6 +214,8 @@ export async function runWorkspacePushSyncService(input) {
             changeCount,
             deleteCount,
             currentTaskIds: input.payload.currentTaskIds,
+            currentTaskWatermarks: input.payload.currentTaskWatermarks ?? new Map(),
+            currentTaskChangeKeys: input.payload.currentTaskChangeKeys ?? new Map(),
             deleteTaskIds: input.payload.deleteTaskIds,
             currentInitiativeIds: input.payload.currentInitiativeIds,
             currentInitiativeWatermarks: input.payload.currentInitiativeWatermarks,
@@ -172,6 +223,7 @@ export async function runWorkspacePushSyncService(input) {
             currentWorkstreamWatermarks: input.payload.currentWorkstreamWatermarks,
             currentAiProfileIds: input.payload.currentAiProfileIds,
             currentAiProfileWatermarks: input.payload.currentAiProfileWatermarks,
+            currentAiProfileChangeKeys: input.payload.currentAiProfileChangeKeys ?? new Map(),
             currentDocumentPaths: input.payload.currentDocumentPaths,
             deleteDocumentPaths: input.payload.deleteDocumentPaths,
             currentDocumentWatermarks: input.payload.currentDocumentWatermarks,
@@ -189,6 +241,7 @@ export async function runWorkspacePushSyncService(input) {
             currentAnnotatedAttachmentSessionWatermarks: input.payload.currentAnnotatedAttachmentSessionWatermarks,
             currentTaskEventWatermarks: input.payload.currentTaskEventWatermarks,
             pushedWatermarks: new Map(),
+            pushedTaskChangeKeys: new Map(),
             emittedEventIds: [],
             appliedTaskUpserts: []
         };
@@ -223,6 +276,8 @@ export async function runWorkspacePushSyncService(input) {
         changeCount,
         deleteCount,
         currentTaskIds: input.payload.currentTaskIds,
+        currentTaskWatermarks: input.payload.currentTaskWatermarks ?? new Map(),
+        currentTaskChangeKeys: input.payload.currentTaskChangeKeys ?? new Map(),
         deleteTaskIds: input.payload.deleteTaskIds,
         currentInitiativeIds: input.payload.currentInitiativeIds,
         currentInitiativeWatermarks: input.payload.currentInitiativeWatermarks,
@@ -230,6 +285,7 @@ export async function runWorkspacePushSyncService(input) {
         currentWorkstreamWatermarks: input.payload.currentWorkstreamWatermarks,
         currentAiProfileIds: input.payload.currentAiProfileIds,
         currentAiProfileWatermarks: input.payload.currentAiProfileWatermarks,
+        currentAiProfileChangeKeys: input.payload.currentAiProfileChangeKeys ?? new Map(),
         currentDocumentPaths: input.payload.currentDocumentPaths,
         deleteDocumentPaths: input.payload.deleteDocumentPaths,
         currentDocumentWatermarks: input.payload.currentDocumentWatermarks,
@@ -247,6 +303,7 @@ export async function runWorkspacePushSyncService(input) {
         currentAnnotatedAttachmentSessionWatermarks: input.payload.currentAnnotatedAttachmentSessionWatermarks,
         currentTaskEventWatermarks: input.payload.currentTaskEventWatermarks,
         pushedWatermarks: input.payload.pushedWatermarks,
+        pushedTaskChangeKeys: input.payload.pushedTaskChangeKeys ?? new Map(),
         emittedEventIds,
         appliedTaskUpserts
     };
@@ -288,10 +345,13 @@ export async function runWorkspacePullSyncService(input) {
                 }
             }
             if (!pullRes.ok) {
+                const pullErrorData = asObjectRecord(pullRes.data);
                 return {
                     success: false,
                     kind: 'pull_http',
                     status: pullRes.status,
+                    errorCode: typeof pullErrorData.code === 'string' ? pullErrorData.code : undefined,
+                    error: typeof pullErrorData.error === 'string' ? pullErrorData.error : undefined,
                     retryAfterMs: pullRes.retryAfterMs,
                     transient: isTransientWorkspaceSyncStatus(pullRes.status),
                     cursor,

package/dist/sync/syncService.test.js

@@ -443,7 +443,7 @@ describe('syncService', () => {
                 status: 200,
                 data: {
                     success: true,
-                    changes: [{ op: 'upsert', task: { id: 't-parent', title: 'Parent', status: 'done', updatedAt: '2026-03-15T20:27:08.000Z' } }],
+                    changes: [{ op: 'upsert', task: { id: 'task-apply-error', title: 'Apply error', status: 'done', updatedAt: '2026-03-15T20:27:08.000Z' } }],
                     nextCursor: null,
                     hasMore: false
                 }
@@ -452,7 +452,7 @@ describe('syncService', () => {
                 ok: false,
                 status: 400,
                 failures: ['/api/taskforce/sync/workspace/apply-local:400'],
-                data: { error: 'Parent tasks cannot be marked done manually; completion is derived from descendants' }
+                data: { error: 'Task apply rejected by local validation' }
             });
             const res = await runWorkspacePullSyncService({
                 resolveCloudAuthUrl: mockResolveCloudAuthUrl,
@@ -463,7 +463,7 @@ describe('syncService', () => {
             expect(res.success).toBe(false);
             expect(res.kind).toBe('apply_all_candidates');
             expect(res.status).toBe(400);
-            expect(res.error).toBe('Parent tasks cannot be marked done manually; completion is derived from descendants');
+            expect(res.error).toBe('Task apply rejected by local validation');
         });
         it('surfaces document decryption failures without failing pull', async () => {
             const previousKey = process.env.TASKFORCE_SYNC_KEY;
@@ -702,6 +702,60 @@ describe('syncService', () => {
             expect(res.statusCode).toBe(0);
             expect(res.transient).toBe(true);
         });
+        it('recovers from missing cloud workspace selection by provisioning and retrying handshake', async () => {
+            vi.mocked(handshakeWorkspace)
+                .mockResolvedValueOnce({
+                ok: false,
+                status: 400,
+                data: {
+                    code: 'WORKSPACE_ID_REQUIRED',
+                    error: 'No cloud workspace is selected. Complete workspace setup first.'
+                }
+            })
+                .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                data: {}
+            });
+            vi.mocked(provisionWorkspace).mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                data: {
+                    success: true,
+                    existing: true
+                }
+            });
+            const res = await ensureCloudWorkspaceReadyForSyncService(baseHandshakeInput);
+            expect(res.success).toBe(true);
+            expect(res.provisioned).toBe(true);
+            expect(provisionWorkspace).toHaveBeenCalledWith(mockResolveCloudAuthUrl, {
+                workspaceId: 'ws-test',
+                name: 'Test Workspace'
+            });
+            expect(handshakeWorkspace).toHaveBeenCalledTimes(2);
+        });
+        it('surfaces provisioning failure when recovering missing cloud workspace selection', async () => {
+            vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
+                ok: false,
+                status: 400,
+                data: {
+                    code: 'WORKSPACE_ID_REQUIRED',
+                    error: 'No cloud workspace is selected. Complete workspace setup first.'
+                }
+            });
+            vi.mocked(provisionWorkspace).mockResolvedValueOnce({
+                ok: false,
+                status: 409,
+                data: {
+                    code: 'WORKSPACE_ID_ALREADY_EXISTS',
+                    error: 'Workspace ID already exists'
+                }
+            });
+            const res = await ensureCloudWorkspaceReadyForSyncService(baseHandshakeInput);
+            expect(res.success).toBe(false);
+            expect(res.statusCode).toBe(409);
+            expect(res.error).toContain('already linked to another cloud account');
+        });
         it('returns failure when cloudAuthConfigured is false', async () => {
             const res = await ensureCloudWorkspaceReadyForSyncService({
                 ...baseHandshakeInput,
@@ -743,6 +797,20 @@ describe('syncService', () => {
             expect(res.error).toContain('already linked to another cloud account');
             expect(res.error).toContain('grant you access');
         });
+        it('does not provision a new cloud workspace during attach-cloud mismatch handling', async () => {
+            vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
+                ok: false,
+                status: 409,
+                data: { code: 'WORKSPACE_ID_MISMATCH', error: 'Workspace mismatch' }
+            });
+            const res = await ensureCloudWorkspaceReadyForSyncService({
+                ...baseHandshakeInput,
+                allowProvisionOnMismatch: false
+            });
+            expect(res.success).toBe(false);
+            expect(res.statusCode).toBe(409);
+            expect(provisionWorkspace).not.toHaveBeenCalled();
+        });
     });
     describe('syncUserGlobalSettingsService transient metadata', () => {
         beforeEach(() => {

package/dist/sync/taskSyncChangeKey.d.ts

@@ -0,0 +1,2 @@
+import type { TaskItem } from '../types.js';
+export declare function buildTaskSyncChangeKey(task: Partial<TaskItem> | null | undefined, archivedValue: boolean): string;