@taskforcehq/taskforce 0.3.301 → 0.3.303

package/dist/server/routes/documents.js

@@ -24,9 +24,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { normalizeTaskDataRelativePath } from '../../storage/objectStorageClient.js';
+import { shouldUseProvisionalTaskReferences } from '../../utils/taskReferences.js';
 import { purgeExpiredDocuments } from '../../storage/documentPurge.js';
 import { parsePlan } from '../../utils/planParser.js';
 import { getCanonicalDocumentName, getReadableDocumentName, isGeneratedDocumentName } from '../../utils/documentNames.js';
+import { requestRuntimeMode } from './shared.js';
 import { parseJsonBody } from '../routes.js';
 export function registerDocumentRoutes(deps) {
     const { addRoute, core, context, requestWorkspaceId, ensureAdminRole, resolveEffectiveObjectStorageConfig, getObjectStorageClient, resolveStorageWorkspaceId, ensureContextUploadAllowed, parseStorageFolderSegments, buildCanonicalWorkspaceAssetRelativePath, inferAssetKindFromPath, appendStorageTelemetry, scanAndRecordDocument, buildTaskAttachmentPayload, workspaceAssetStore, taskAssetStore, normalizeDocumentPathInput, getAssetMetadata, getCanonicalAssetMetadata, documentRetentionDays, appendDocumentPurgeHistory, markAssetDeleted, isAssetDeleted, clearAssetDeleted, ensureWithinDir, sanitizeDownloadFilename, contentTypeForExt, inferInlineDocumentFromPath, resolveCanonicalDocumentRead, inferWorkspaceIdFromStoragePath, inferTaskIdFromStoragePath, } = deps;
@@ -1097,7 +1099,10 @@ export function registerDocumentRoutes(deps) {
                         type: node.type || 'feature',
                         priority: typeof node.priority === 'number' ? node.priority : 2,
                         status: 'task',
-                    }, { workspaceId });
+                    }, {
+                        workspaceId,
+                        provisionalLocalReference: shouldUseProvisionalTaskReferences(requestRuntimeMode(req))
+                    });
                     created.push(taskItem.id);
                     totalCreated++;
                 }

package/dist/server/routes/shared.d.ts

@@ -30,6 +30,6 @@ export declare function makeResolveAdminRequestActor(core: TaskforceCore, contex
     systemRole: "system_admin" | "user";
 };
 export declare function makeAuditAdminAction(core: TaskforceCore, context: RouteContext): (req: IncomingMessage, action: string, details: Record<string, unknown>) => void;
-export declare function makeAuditAuthAction(core: TaskforceCore, requestWorkspaceId: (req: IncomingMessage) => string): (req: IncomingMessage, action: string, details: Record<string, unknown>) => void;
+export declare function makeAuditAuthAction(core: TaskforceCore, requestWorkspaceId: (req: IncomingMessage) => string, context: RouteContext): (req: IncomingMessage, action: string, details: Record<string, unknown>) => void;
 export declare function makeRequireCloudRuntime(context: RouteContext): (res: ServerResponse, feature: string) => boolean;
 export declare function makeEnsureCloudPlanData(context: RouteContext): (req: IncomingMessage, res: ServerResponse) => boolean;

package/dist/server/routes/shared.js

@@ -167,9 +167,11 @@ export function makeEnsureAppAccess(core, context) {
             return true;
         const code = accountAccess.gate === 'plan_selection_required'
             ? 'PLAN_SELECTION_REQUIRED'
-            : accountAccess.gate === 'misconfigured'
-                ? 'ACCOUNT_ACCESS_MISCONFIGURED'
-                : 'ACCOUNT_ENTITLEMENT_REQUIRED';
+            : accountAccess.gate === 'checkout_pending'
+                ? 'CHECKOUT_PENDING'
+                : accountAccess.gate === 'misconfigured'
+                    ? 'ACCOUNT_ACCESS_MISCONFIGURED'
+                    : 'ACCOUNT_ENTITLEMENT_REQUIRED';
         res.writeHead(403, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({
             error: accountAccess.message || 'This account cannot access the app.',
@@ -257,13 +259,21 @@ export function makeAuditAdminAction(core, context) {
         console.info(`[Taskforce Admin Audit] ${JSON.stringify(payload)}`);
     };
 }
-export function makeAuditAuthAction(core, requestWorkspaceId) {
+export function makeAuditAuthAction(core, requestWorkspaceId, context) {
     return function auditAuthAction(req, action, details) {
+        const authConfig = context.authConfig;
+        const resolvedAccess = authConfig?.enabled ? resolveRequestAccess(req, authConfig) : null;
+        const actorUserId = resolvedAccess?.authenticated && resolvedAccess.userId && resolvedAccess.userId !== 'anonymous'
+            ? resolvedAccess.userId
+            : requestUserId(req);
+        const actorRole = resolvedAccess?.authenticated
+            ? String(resolvedAccess.role || '').trim().toLowerCase() || requestRole(req)
+            : requestRole(req);
         const payload = {
             ts: new Date().toISOString(),
             action,
-            actorUserId: requestUserId(req),
-            actorRole: requestRole(req),
+            actorUserId,
+            actorRole,
             workspaceId: requestWorkspaceId(req),
             details
         };

package/dist/server/routes/sync.integration.test.js

@@ -140,6 +140,49 @@ describe('Server Routes Workspace Sync Integration', () => {
         expect(task?.status).toBe('in-progress');
         expect(defaultWorkspaceTasks.find((item) => item.id === 'task-cloud-1')).toBeUndefined();
     });
+    it('lets the cloud task keep a colliding reference number during apply-local and records a diagnostic', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-task-ref-collision-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const localTask = core.createTask({ title: 'Local incumbent' }, { workspaceId });
+        expect(localTask.referenceLabel).toBe('T-1');
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-cloud-ref-1',
+                        title: 'Cloud winner',
+                        status: 'task',
+                        referenceNumber: 1,
+                        updatedAt: '2026-04-10T16:00:00.000Z'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        expect(reloadedCore.getTask('task-cloud-ref-1', workspaceId)?.referenceLabel).toBe('T-1');
+        expect(reloadedCore.getTask(localTask.id, workspaceId)?.referenceLabel).toBe('T-2');
+        expect(reloadedCore.listSyncEvents(workspaceId, 10)).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                eventType: 'apply',
+                status: 'error',
+                errorMessage: 'Detected task reference number mismatch during normal sync.',
+                details: expect.objectContaining({
+                    referenceLabel: 'T-1',
+                    existingTaskId: localTask.id,
+                    taskId: 'task-cloud-ref-1'
+                })
+            })
+        ]));
+    });
     it('persists synced comments via apply-local route', async () => {
         const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-comments-');
         const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
@@ -1268,6 +1311,166 @@ describe('Server Routes Workspace Sync Integration', () => {
             })
         ]);
     });
+    it('lets the cloud document ref win during normal sync apply and records a diagnostic', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-doc-ref-drift-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createTask({
+            id: 'task-doc-ref-drift-1',
+            title: 'Task with drifting synced markdown asset',
+            status: 'task'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const seededStore = new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId());
+        seededStore.upsertAsset({
+            assetId: 'asset-doc-ref-drift-1',
+            workspaceId,
+            kind: 'document',
+            originalFilename: 'phase1-ref-drift.md',
+            mimeType: 'text/markdown',
+            storageProvider: 'local',
+            storageKey: 'docs/phase1-ref-drift.md',
+            contentSha256: 'sha-doc-ref-drift-local',
+            sizeBytes: 10,
+            documentId: 'doc-ref-drift-1',
+            referenceNumber: 12,
+            createdAt: '2026-03-17T11:55:00.000Z',
+            updatedAt: '2026-03-17T11:55:00.000Z'
+        });
+        seededStore.upsertLink({
+            workspaceId,
+            assetId: 'asset-doc-ref-drift-1',
+            taskId: 'task-doc-ref-drift-1',
+            role: 'attachment',
+            updatedAt: '2026-03-17T11:55:00.000Z',
+            deletedAt: null
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'document-upsert',
+                    path: 'docs/phase1-ref-drift.md',
+                    updatedAt: '2026-03-17T12:00:00.000Z',
+                    content: '# cloud canonical markdown\n',
+                    assetId: 'asset-doc-ref-drift-1',
+                    documentId: 'doc-ref-drift-1',
+                    referenceNumber: 18,
+                    version: 2,
+                    taskId: 'task-doc-ref-drift-1',
+                    originalFilename: 'phase1-ref-drift.md',
+                    linkRole: 'attachment'
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const store = new WorkspaceAssetStore(reloadedCore.getDatabaseAdapter(), reloadedCore.getTenantId());
+        const asset = store.get('asset-doc-ref-drift-1', workspaceId);
+        const syncEvents = reloadedCore.listSyncEvents(workspaceId, 20);
+        expect(asset).toEqual(expect.objectContaining({
+            assetId: 'asset-doc-ref-drift-1',
+            referenceNumber: 18,
+            version: 2
+        }));
+        expect(syncEvents).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                eventType: 'apply',
+                status: 'error',
+                errorMessage: 'Detected document reference number mismatch during normal sync.',
+                details: expect.objectContaining({
+                    assetId: 'asset-doc-ref-drift-1',
+                    existingReferenceNumber: 12,
+                    incomingReferenceNumber: 18
+                })
+            })
+        ]));
+    });
+    it('lets the cloud image ref win during normal sync apply and records a diagnostic', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-image-ref-drift-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createTask({
+            id: 'task-image-ref-drift-1',
+            title: 'Task with drifting synced image asset',
+            status: 'task'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const seededStore = new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId());
+        seededStore.upsertAsset({
+            assetId: 'asset-image-ref-drift-1',
+            workspaceId,
+            kind: 'image',
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            storageProvider: 'local',
+            storageKey: 'workspaces/workspace-local-active/assets/images/hero.png',
+            contentSha256: 'sha-image-ref-drift-local',
+            sizeBytes: 10,
+            referenceNumber: 12,
+            createdAt: '2026-03-17T11:55:00.000Z',
+            updatedAt: '2026-03-17T11:55:00.000Z'
+        });
+        seededStore.upsertLink({
+            workspaceId,
+            assetId: 'asset-image-ref-drift-1',
+            taskId: 'task-image-ref-drift-1',
+            role: 'image',
+            updatedAt: '2026-03-17T11:55:00.000Z',
+            deletedAt: null
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'asset-upsert',
+                    path: 'workspaces/workspace-local-active/assets/images/hero.png',
+                    updatedAt: '2026-03-17T12:05:00.000Z',
+                    contentBase64: Buffer.from('cloud-hero').toString('base64'),
+                    assetId: 'asset-image-ref-drift-1',
+                    kind: 'image',
+                    mimeType: 'image/png',
+                    referenceNumber: 18,
+                    taskId: 'task-image-ref-drift-1',
+                    originalFilename: 'hero.png',
+                    linkRole: 'image'
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const store = new WorkspaceAssetStore(reloadedCore.getDatabaseAdapter(), reloadedCore.getTenantId());
+        const asset = store.get('asset-image-ref-drift-1', workspaceId);
+        const syncEvents = reloadedCore.listSyncEvents(workspaceId, 20);
+        expect(asset).toEqual(expect.objectContaining({
+            assetId: 'asset-image-ref-drift-1',
+            referenceNumber: 18
+        }));
+        expect(syncEvents).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                eventType: 'apply',
+                status: 'error',
+                errorMessage: 'Detected asset reference number mismatch during normal sync.',
+                details: expect.objectContaining({
+                    assetId: 'asset-image-ref-drift-1',
+                    existingReferenceNumber: 12,
+                    incomingReferenceNumber: 18
+                })
+            })
+        ]));
+    });
     it('round-trips cloud attachment links for canonical markdown and file assets into local apply', async () => {
         const cloudProjectRoot = createIsolatedProjectRoot('taskforce-sync-cloud-link-roundtrip-cloud-');
         const localProjectRoot = createIsolatedProjectRoot('taskforce-sync-cloud-link-roundtrip-local-');
@@ -1487,6 +1690,93 @@ describe('Server Routes Workspace Sync Integration', () => {
             })
         ]);
     });
+    it('omits local provisional reference fields from authenticated pull payloads', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-pull-task-ref-payload-');
+        const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(seedCore);
+        const created = seedCore.createTask({
+            title: 'Offline draft',
+            status: 'task'
+        }, {
+            workspaceId,
+            provisionalLocalReference: true
+        });
+        expect(created.localReferenceNumber).toBe(1);
+        expect(created.referenceLabel).toBe('LT-1');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const routes = createRoutes(core, { authConfig });
+        const pullMatch = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
+        expect(pullMatch).toBeTruthy();
+        const cookie = createAuthCookie(workspaceId);
+        const pullReq = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-local-active&limit=200', undefined, { cookie });
+        const pullRes = createMockRes();
+        await pullMatch?.handler(pullReq, pullRes, {});
+        expect(pullRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const pullBody = readJsonBody(pullRes);
+        const upsert = (Array.isArray(pullBody?.changes) ? pullBody.changes : [])
+            .find((change) => change?.op === 'upsert' && change?.task?.id === created.id);
+        expect(upsert?.task).toEqual(expect.objectContaining({
+            id: created.id,
+            title: 'Offline draft',
+            referenceNumber: null
+        }));
+        expect(upsert?.task).not.toHaveProperty('localReferenceNumber');
+        expect(upsert?.task).not.toHaveProperty('referenceLabel');
+    });
+    it('returns a pushed provisional task on pull even when the caller cursor is newer than the stale local watermark', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-push-pull-provisional-task-');
+        const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(seedCore);
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const routes = createRoutes(core, { authConfig });
+        const pushMatch = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
+        const pullMatch = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
+        expect(pushMatch).toBeTruthy();
+        expect(pullMatch).toBeTruthy();
+        const cookie = createAuthCookie(workspaceId);
+        const taskId = 'task-provisional-roundtrip-1';
+        const staleUpdatedAt = '2026-04-11T21:29:04.121Z';
+        const pushReq = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
+            workspaceId,
+            idempotencyKey: 'task-provisional-roundtrip-1',
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: taskId,
+                        title: 'Offline provisional task',
+                        status: 'task',
+                        createdAt: '2026-04-11T21:28:52.410Z',
+                        updatedAt: staleUpdatedAt,
+                        referenceNumber: null
+                    }
+                }
+            ]
+        }, { cookie });
+        const pushRes = createMockRes();
+        await pushMatch?.handler(pushReq, pushRes, {});
+        expect(pushRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const persisted = core.getTask(taskId, workspaceId);
+        expect(persisted?.referenceNumber).toBe(1);
+        expect(Date.parse(String(persisted?.updatedAt || ''))).toBeGreaterThan(Date.parse(staleUpdatedAt));
+        const cursor = Buffer.from(JSON.stringify({
+            u: '2026-04-11T21:29:05.000Z',
+            id: 'seed'
+        })).toString('base64url');
+        const pullReq = createMockReq('GET', `/api/taskforce/sync/workspace/pull?workspaceId=${workspaceId}&limit=200&cursor=${cursor}`, undefined, { cookie });
+        const pullRes = createMockRes();
+        await pullMatch?.handler(pullReq, pullRes, {});
+        expect(pullRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const pullBody = readJsonBody(pullRes);
+        const upsert = (Array.isArray(pullBody?.changes) ? pullBody.changes : [])
+            .find((change) => change?.op === 'upsert' && change?.task?.id === taskId);
+        expect(upsert?.task).toEqual(expect.objectContaining({
+            id: taskId,
+            title: 'Offline provisional task',
+            referenceNumber: 1
+        }));
+    });
     it('keeps document deleted when push batch includes upsert and delete for same path', async () => {
         const projectRoot = createIsolatedProjectRoot('taskforce-sync-push-doc-delete-wins-');
         const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });