@taskforcehq/taskforce 0.3.305 → 0.3.307

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

@@ -3,6 +3,7 @@ import { Readable } from 'stream';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { createHash } from 'crypto';
 import { TaskforceCore } from '../../core/Taskforce';
 import { createRoutes, matchRoute } from '../routes';
 import { createSessionTokenCookie } from '../auth';
@@ -110,6 +111,7 @@ describe('Server Routes Workspace Sync Integration', () => {
         const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-');
         const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
         core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const basePath = core.getPaths().basePath;
         const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
         const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
         expect(match).toBeTruthy();
@@ -344,6 +346,8 @@ describe('Server Routes Workspace Sync Integration', () => {
                         username: 'codex',
                         icon: 'Bot',
                         color: '#0ea5e9',
+                        avatarUrl: '/api/taskforce/context/workspaces%2Fworkspace-sync-ai%2Fassets%2Fimages%2Fai-profiles%2Fai-profile-codex%2Favatar%2Favatar.webp',
+                        avatarSourceUrl: '/api/taskforce/context/workspaces%2Fworkspace-sync-ai%2Fassets%2Fimages%2Fai-profiles%2Fai-profile-codex%2Favatar%2Fsource.webp',
                         description: 'Terminal-first coding agent',
                         role: 'Implementer',
                         provider: 'OpenAI',
@@ -369,7 +373,9 @@ describe('Server Routes Workspace Sync Integration', () => {
                 role: 'Implementer',
                 provider: 'OpenAI',
                 model: 'gpt-5.4',
-                surfaceType: 'coding_tool'
+                surfaceType: 'coding_tool',
+                avatarUrl: '/api/taskforce/context/workspaces%2Fworkspace-sync-ai%2Fassets%2Fimages%2Fai-profiles%2Fai-profile-codex%2Favatar%2Favatar.webp',
+                avatarSourceUrl: '/api/taskforce/context/workspaces%2Fworkspace-sync-ai%2Fassets%2Fimages%2Fai-profiles%2Fai-profile-codex%2Favatar%2Fsource.webp'
             })
         ]);
     });
@@ -1319,7 +1325,7 @@ describe('Server Routes Workspace Sync Integration', () => {
             })
         ]);
     });
-    it('lets the cloud document ref win during normal sync apply and records a diagnostic', async () => {
+    it('lets the cloud document ref win during normal sync apply without recording a sync error', async () => {
         const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-doc-ref-drift-');
         const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
         core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
@@ -1381,26 +1387,17 @@ describe('Server Routes Workspace Sync Integration', () => {
         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);
+        const mismatchEvents = reloadedCore.listSyncEvents(workspaceId, 20).filter((event) => event.eventType === 'apply'
+            && event.status === 'error'
+            && event.errorMessage === 'Detected document reference number mismatch during normal sync.');
         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
-                })
-            })
-        ]));
+        expect(mismatchEvents).toHaveLength(0);
     });
-    it('lets the cloud image ref win during normal sync apply and records a diagnostic', async () => {
+    it('lets the cloud image ref win during normal sync apply without recording a sync error', async () => {
         const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-image-ref-drift-');
         const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
         core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
@@ -1461,23 +1458,94 @@ describe('Server Routes Workspace Sync Integration', () => {
         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);
+        const mismatchEvents = reloadedCore.listSyncEvents(workspaceId, 20).filter((event) => event.eventType === 'apply'
+            && event.status === 'error'
+            && event.errorMessage === 'Detected asset reference number mismatch during normal sync.');
         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
-                })
-            })
-        ]));
+        expect(mismatchEvents).toHaveLength(0);
+    });
+    it('converges unchanged image reference drift during normal sync so later pulls stop re-logging it', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-image-ref-converge-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createTask({
+            id: 'task-image-ref-converge-1',
+            title: 'Task with converging synced image asset',
+            status: 'task'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const basePath = core.getPaths().basePath;
+        const relativeAssetPath = 'workspaces/workspace-local-active/assets/images/hero-converge.png';
+        const absoluteAssetPath = path.join(basePath, relativeAssetPath);
+        fs.mkdirSync(path.dirname(absoluteAssetPath), { recursive: true });
+        fs.writeFileSync(absoluteAssetPath, 'cloud-hero');
+        const seededStore = new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId());
+        seededStore.upsertAsset({
+            assetId: 'asset-image-ref-converge-1',
+            workspaceId,
+            kind: 'image',
+            originalFilename: 'hero-converge.png',
+            mimeType: 'image/png',
+            storageProvider: 'local',
+            storageKey: relativeAssetPath,
+            contentSha256: createHash('sha256').update('cloud-hero').digest('hex'),
+            sizeBytes: Buffer.byteLength('cloud-hero'),
+            referenceNumber: 12,
+            createdAt: '2026-03-17T11:55:00.000Z',
+            updatedAt: '2026-03-17T12:05:00.000Z'
+        });
+        seededStore.upsertLink({
+            workspaceId,
+            assetId: 'asset-image-ref-converge-1',
+            taskId: 'task-image-ref-converge-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 body = {
+            changes: [
+                {
+                    op: 'asset-upsert',
+                    path: relativeAssetPath,
+                    updatedAt: '2026-03-17T12:05:00.000Z',
+                    contentBase64: Buffer.from('cloud-hero').toString('base64'),
+                    assetId: 'asset-image-ref-converge-1',
+                    kind: 'image',
+                    mimeType: 'image/png',
+                    referenceNumber: 18,
+                    taskId: 'task-image-ref-converge-1',
+                    originalFilename: 'hero-converge.png',
+                    linkRole: 'image'
+                }
+            ]
+        };
+        const firstReq = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', body, { 'x-taskforce-workspace-id': workspaceId });
+        const firstRes = createMockRes();
+        await match?.handler(firstReq, firstRes, {});
+        expect(firstRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const secondReq = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', body, { 'x-taskforce-workspace-id': workspaceId });
+        const secondRes = createMockRes();
+        await match?.handler(secondReq, secondRes, {});
+        expect(secondRes.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-converge-1', workspaceId);
+        const mismatchEvents = reloadedCore.listSyncEvents(workspaceId, 20).filter((event) => event.eventType === 'apply'
+            && event.status === 'error'
+            && event.errorMessage === 'Detected asset reference number mismatch during normal sync.');
+        expect(asset).toEqual(expect.objectContaining({
+            assetId: 'asset-image-ref-converge-1',
+            referenceNumber: 18
+        }));
+        expect(mismatchEvents).toHaveLength(0);
     });
     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-');
@@ -1608,6 +1676,227 @@ describe('Server Routes Workspace Sync Integration', () => {
             })
         ]);
     });
+    it('round-trips planning attachment links through pull and apply-local routes', async () => {
+        const cloudProjectRoot = createIsolatedProjectRoot('taskforce-sync-planning-link-cloud-');
+        const localProjectRoot = createIsolatedProjectRoot('taskforce-sync-planning-link-local-');
+        const cloudCore = new TaskforceCore({ projectRoot: cloudProjectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(cloudCore);
+        cloudCore.createInitiative({
+            id: 'initiative-cloud-link-roundtrip-1',
+            title: 'Cloud initiative attachment target',
+            createdAt: '2026-03-18T09:00:00.000Z',
+            updatedAt: '2026-03-18T09:00:00.000Z'
+        }, workspaceId);
+        cloudCore.createWorkstream({
+            id: 'workstream-cloud-link-roundtrip-1',
+            initiativeId: 'initiative-cloud-link-roundtrip-1',
+            title: 'Cloud workstream attachment target',
+            createdAt: '2026-03-18T09:00:00.000Z',
+            updatedAt: '2026-03-18T09:00:00.000Z'
+        }, workspaceId);
+        const cloudBasePath = cloudCore.getPaths().basePath;
+        const cloudStore = new WorkspaceAssetStore(cloudCore.getDatabaseAdapter(), cloudCore.getTenantId());
+        const markdownPath = `workspaces/${workspaceId}/assets/documents/asset-cloud-planning-link-plan.md`;
+        const filePath = `workspaces/${workspaceId}/assets/files/asset-cloud-planning-link-notes.txt`;
+        fs.mkdirSync(path.dirname(path.join(cloudBasePath, markdownPath)), { recursive: true });
+        fs.mkdirSync(path.dirname(path.join(cloudBasePath, filePath)), { recursive: true });
+        fs.writeFileSync(path.join(cloudBasePath, markdownPath), '# planning sync\n', 'utf8');
+        fs.writeFileSync(path.join(cloudBasePath, filePath), 'planning attachment', 'utf8');
+        cloudStore.upsertAsset({
+            assetId: 'asset-cloud-planning-link-doc-1',
+            workspaceId,
+            kind: 'document',
+            originalFilename: 'plan.md',
+            mimeType: 'text/markdown',
+            storageProvider: 'local',
+            storageKey: markdownPath,
+            contentSha256: 'planning-doc-roundtrip-hash',
+            sizeBytes: '# planning sync\n'.length,
+            documentId: 'doc-cloud-planning-link-1',
+            version: 1,
+            isLatest: true,
+            createdAt: '2026-03-18T09:00:00.000Z',
+            updatedAt: '2026-03-18T09:00:00.000Z'
+        });
+        cloudStore.upsertLink({
+            workspaceId,
+            assetId: 'asset-cloud-planning-link-doc-1',
+            targetType: 'initiative',
+            targetId: 'initiative-cloud-link-roundtrip-1',
+            role: 'attachment',
+            updatedAt: '2026-03-18T10:00:00.000Z'
+        });
+        cloudStore.upsertAsset({
+            assetId: 'asset-cloud-planning-link-file-1',
+            workspaceId,
+            kind: 'file',
+            originalFilename: 'notes.txt',
+            mimeType: 'text/plain',
+            storageProvider: 'local',
+            storageKey: filePath,
+            contentSha256: 'planning-file-roundtrip-hash',
+            sizeBytes: 'planning attachment'.length,
+            isLatest: true,
+            createdAt: '2026-03-18T09:00:00.000Z',
+            updatedAt: '2026-03-18T09:00:00.000Z'
+        });
+        cloudStore.upsertLink({
+            workspaceId,
+            assetId: 'asset-cloud-planning-link-file-1',
+            targetType: 'workstream',
+            targetId: 'workstream-cloud-link-roundtrip-1',
+            role: 'attachment',
+            updatedAt: '2026-03-18T10:00:01.000Z'
+        });
+        const cloudRoutes = createRoutes(cloudCore, { authConfig });
+        const pullMatch = matchRoute('GET', '/api/taskforce/sync/workspace/pull', cloudRoutes);
+        expect(pullMatch).toBeTruthy();
+        const cookie = createAuthCookie(workspaceId);
+        const pullReq = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-local-active&limit=50&cursor=eyJ1IjoiMjAyNi0wMy0xOFQwOTozMDowMC4wMDBaIiwiaWQiOiJzZWVkIn0', undefined, { cookie });
+        const pullRes = createMockRes();
+        await pullMatch?.handler(pullReq, pullRes, {});
+        expect(pullRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const pullBody = readJsonBody(pullRes);
+        const pulledChanges = Array.isArray(pullBody?.changes) ? pullBody.changes : [];
+        expect(pulledChanges).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                op: 'document-upsert',
+                path: markdownPath,
+                assetId: 'asset-cloud-planning-link-doc-1',
+                linkTargetType: 'initiative',
+                linkTargetId: 'initiative-cloud-link-roundtrip-1',
+                originalFilename: 'plan.md',
+                linkRole: 'attachment'
+            }),
+            expect.objectContaining({
+                op: 'asset-upsert',
+                path: filePath,
+                assetId: 'asset-cloud-planning-link-file-1',
+                linkTargetType: 'workstream',
+                linkTargetId: 'workstream-cloud-link-roundtrip-1',
+                originalFilename: 'notes.txt',
+                linkRole: 'attachment'
+            })
+        ]));
+        const localCore = new TaskforceCore({ projectRoot: localProjectRoot, storagePath: '.taskforce' });
+        localCore.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        localCore.createInitiative({
+            id: 'initiative-cloud-link-roundtrip-1',
+            title: 'Local initiative attachment target',
+            createdAt: '2026-03-18T09:00:00.000Z',
+            updatedAt: '2026-03-18T09:00:00.000Z'
+        }, workspaceId);
+        localCore.createWorkstream({
+            id: 'workstream-cloud-link-roundtrip-1',
+            initiativeId: 'initiative-cloud-link-roundtrip-1',
+            title: 'Local workstream attachment target',
+            createdAt: '2026-03-18T09:00:00.000Z',
+            updatedAt: '2026-03-18T09:00:00.000Z'
+        }, workspaceId);
+        const localRoutes = createRoutes(localCore, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const applyMatch = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', localRoutes);
+        expect(applyMatch).toBeTruthy();
+        const applyReq = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', { changes: pulledChanges }, { 'x-taskforce-workspace-id': workspaceId });
+        const applyRes = createMockRes();
+        await applyMatch?.handler(applyReq, applyRes, {});
+        expect(applyRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedLocalCore = new TaskforceCore({ projectRoot: localProjectRoot, storagePath: '.taskforce' });
+        const reloadedStore = new WorkspaceAssetStore(reloadedLocalCore.getDatabaseAdapter(), reloadedLocalCore.getTenantId());
+        expect(fs.readFileSync(path.join(reloadedLocalCore.getPaths().basePath, markdownPath), 'utf8')).toBe('# planning sync\n');
+        expect(fs.readFileSync(path.join(reloadedLocalCore.getPaths().basePath, filePath), 'utf8')).toBe('planning attachment');
+        expect(reloadedStore.listLinksForAsset('asset-cloud-planning-link-doc-1', workspaceId)).toEqual([
+            expect.objectContaining({
+                targetType: 'initiative',
+                targetId: 'initiative-cloud-link-roundtrip-1',
+                taskId: null,
+                role: 'attachment',
+                deletedAt: null
+            })
+        ]);
+        expect(reloadedStore.listLinksForAsset('asset-cloud-planning-link-file-1', workspaceId)).toEqual([
+            expect.objectContaining({
+                targetType: 'workstream',
+                targetId: 'workstream-cloud-link-roundtrip-1',
+                taskId: null,
+                role: 'attachment',
+                deletedAt: null
+            })
+        ]);
+    });
+    it('pushes document attachment links when only the link metadata changed locally', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-doc-link-only-push-');
+        const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(seedCore);
+        seedCore.createTask({
+            id: 'task-doc-link-only-push-1',
+            title: 'Document link target',
+            status: 'task'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const seedBasePath = seedCore.getPaths().basePath;
+        const relativeDocPath = `workspaces/${workspaceId}/assets/documents/asset-doc-link-only-push-plan.md`;
+        const absoluteDocPath = path.join(seedBasePath, relativeDocPath);
+        const content = '# already synced\n';
+        fs.mkdirSync(path.dirname(absoluteDocPath), { recursive: true });
+        fs.writeFileSync(absoluteDocPath, content, 'utf8');
+        const contentHash = createHash('sha256').update(content).digest('hex');
+        seedCore.upsertDocumentWatermark(workspaceId, relativeDocPath, contentHash, '2026-03-18T13:30:00.000Z');
+        const seedStore = new WorkspaceAssetStore(seedCore.getDatabaseAdapter(), seedCore.getTenantId());
+        seedStore.upsertAsset({
+            assetId: 'asset-doc-link-only-push-1',
+            workspaceId,
+            kind: 'document',
+            originalFilename: 'plan.md',
+            mimeType: 'text/markdown',
+            storageProvider: 'local',
+            storageKey: relativeDocPath,
+            contentSha256: contentHash,
+            sizeBytes: Buffer.byteLength(content, 'utf8'),
+            documentId: 'doc-link-only-push-1',
+            version: 1,
+            isLatest: true,
+            createdAt: '2026-03-18T13:30:00.000Z',
+            updatedAt: '2026-03-18T13:30:00.000Z'
+        });
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const routes = createRoutes(core, { authConfig });
+        const pushMatch = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
+        expect(pushMatch).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
+            workspaceId,
+            idempotencyKey: 'doc-link-only-push-1',
+            changes: [
+                {
+                    op: 'document-upsert',
+                    path: relativeDocPath,
+                    updatedAt: '2026-03-18T14:45:00.000Z',
+                    content,
+                    assetId: 'asset-doc-link-only-push-1',
+                    documentId: 'doc-link-only-push-1',
+                    referenceNumber: 12,
+                    version: 1,
+                    taskId: 'task-doc-link-only-push-1',
+                    originalFilename: 'plan.md',
+                    linkRole: 'attachment'
+                }
+            ]
+        }, { cookie: createAuthCookie(workspaceId) });
+        const res = createMockRes();
+        await pushMatch?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const reloadedStore = new WorkspaceAssetStore(reloadedCore.getDatabaseAdapter(), reloadedCore.getTenantId());
+        expect(reloadedStore.listLinksForAsset('asset-doc-link-only-push-1', workspaceId)).toEqual([
+            expect.objectContaining({
+                taskId: 'task-doc-link-only-push-1',
+                role: 'attachment',
+                updatedAt: '2026-03-18T14:45:00.000Z',
+                deletedAt: null
+            })
+        ]);
+    });
     it('propagates document-delete through authenticated push and omits deleted doc from pull payload', async () => {
         const projectRoot = createIsolatedProjectRoot('taskforce-sync-push-pull-doc-delete-');
         const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
@@ -1992,9 +2281,9 @@ describe('Server Routes Workspace Sync Integration', () => {
             workspaceId,
             eventType: 'apply',
             status: 'error',
-            errorMessage: 'Detected asset reference number mismatch during normal sync.',
+            errorMessage: 'Detected task reference number mismatch during normal sync.',
             details: {
-                path: 'workspaces/workspace-local-active/assets/images/hero.png',
+                taskId: 'task-1',
                 existingReferenceNumber: 12,
                 incomingReferenceNumber: 18
             }
@@ -2013,15 +2302,319 @@ describe('Server Routes Workspace Sync Integration', () => {
             expect.objectContaining({
                 eventType: 'apply',
                 status: 'error',
-                errorMessage: 'Detected asset reference number mismatch during normal sync.',
+                errorMessage: 'Detected task reference number mismatch during normal sync.',
                 details: expect.objectContaining({
-                    path: 'workspaces/workspace-local-active/assets/images/hero.png',
+                    taskId: 'task-1',
                     existingReferenceNumber: 12,
                     incomingReferenceNumber: 18
                 })
             })
         ]));
     });
+    it('repairs orphaned startup document and asset metadata and exposes the recovered metadata through snapshots', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-repair-startup-recover-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const basePath = core.getPaths().basePath;
+        const relativeDocPath = 'docs/recovered-startup-note.md';
+        const relativeAssetPath = `workspaces/${workspaceId}/assets/images/recovered-startup-image.png`;
+        const absoluteDocPath = path.join(basePath, relativeDocPath);
+        const absoluteAssetPath = path.join(basePath, relativeAssetPath);
+        const assetBuffer = Buffer.from('recovered-image-binary');
+        fs.mkdirSync(path.dirname(absoluteDocPath), { recursive: true });
+        fs.mkdirSync(path.dirname(absoluteAssetPath), { recursive: true });
+        fs.writeFileSync(absoluteDocPath, '# repaired startup note\n', 'utf8');
+        fs.writeFileSync(absoluteAssetPath, assetBuffer);
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const documentsMatch = matchRoute('GET', '/api/taskforce/sync/workspace/documents', routes);
+        const assetsMatch = matchRoute('GET', '/api/taskforce/sync/workspace/assets', routes);
+        const repairMatch = matchRoute('POST', '/api/taskforce/sync/workspace/repair-startup', routes);
+        expect(documentsMatch).toBeTruthy();
+        expect(assetsMatch).toBeTruthy();
+        expect(repairMatch).toBeTruthy();
+        const beforeDocumentsReq = createMockReq('GET', `/api/taskforce/sync/workspace/documents?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const beforeDocumentsRes = createMockRes();
+        await documentsMatch?.handler(beforeDocumentsReq, beforeDocumentsRes, {});
+        expect(beforeDocumentsRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const beforeDocumentsBody = readJsonBody(beforeDocumentsRes);
+        const beforeDoc = (Array.isArray(beforeDocumentsBody?.documents) ? beforeDocumentsBody.documents : [])
+            .find((entry) => entry.path === relativeDocPath);
+        expect(beforeDoc).toBeUndefined();
+        const beforeAssetsReq = createMockReq('GET', `/api/taskforce/sync/workspace/assets?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const beforeAssetsRes = createMockRes();
+        await assetsMatch?.handler(beforeAssetsReq, beforeAssetsRes, {});
+        expect(beforeAssetsRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const beforeAssetsBody = readJsonBody(beforeAssetsRes);
+        expect(beforeAssetsBody.assets).toEqual([]);
+        const repairReq = createMockReq('POST', '/api/taskforce/sync/workspace/repair-startup', { workspaceId }, { 'x-taskforce-workspace-id': workspaceId });
+        const repairRes = createMockRes();
+        await repairMatch?.handler(repairReq, repairRes, {});
+        expect(repairRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        expect(readJsonBody(repairRes)).toEqual(expect.objectContaining({
+            success: true,
+            applied: 2,
+            skipped: 0,
+            failed: 0
+        }));
+        const afterDocumentsReq = createMockReq('GET', `/api/taskforce/sync/workspace/documents?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const afterDocumentsRes = createMockRes();
+        await documentsMatch?.handler(afterDocumentsReq, afterDocumentsRes, {});
+        expect(afterDocumentsRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const afterDocumentsBody = readJsonBody(afterDocumentsRes);
+        const repairedDoc = (Array.isArray(afterDocumentsBody?.documents) ? afterDocumentsBody.documents : [])
+            .find((entry) => entry.path === relativeDocPath);
+        expect(repairedDoc).toEqual(expect.objectContaining({
+            path: relativeDocPath,
+            content: '# repaired startup note\n',
+            assetId: expect.stringMatching(/^asset-/),
+            documentId: expect.stringMatching(/^doc-/),
+            originalFilename: 'recovered-startup-note.md'
+        }));
+        const afterAssetsReq = createMockReq('GET', `/api/taskforce/sync/workspace/assets?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const afterAssetsRes = createMockRes();
+        await assetsMatch?.handler(afterAssetsReq, afterAssetsRes, {});
+        expect(afterAssetsRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const afterAssetsBody = readJsonBody(afterAssetsRes);
+        const repairedAsset = (Array.isArray(afterAssetsBody?.assets) ? afterAssetsBody.assets : [])
+            .find((entry) => entry.path === relativeAssetPath);
+        expect(repairedAsset).toEqual(expect.objectContaining({
+            path: relativeAssetPath,
+            assetId: expect.stringMatching(/^asset-/),
+            kind: 'image',
+            mimeType: 'image/png',
+            originalFilename: 'recovered-startup-image.png',
+            linkRole: 'image',
+            contentBase64: assetBuffer.toString('base64')
+        }));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const store = new WorkspaceAssetStore(reloadedCore.getDatabaseAdapter(), reloadedCore.getTenantId());
+        expect(store.getByStorageKey(relativeDocPath, workspaceId)).toEqual(expect.objectContaining({
+            storageKey: relativeDocPath,
+            kind: 'document',
+            mimeType: 'text/markdown',
+            originalFilename: 'recovered-startup-note.md',
+            documentId: expect.stringMatching(/^doc-/)
+        }));
+        expect(store.getByStorageKey(relativeAssetPath, workspaceId)).toEqual(expect.objectContaining({
+            storageKey: relativeAssetPath,
+            kind: 'image',
+            mimeType: 'image/png',
+            originalFilename: 'recovered-startup-image.png'
+        }));
+    });
+    it('revives stale startup tombstones with the original metadata identifiers when local files are newer', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-repair-startup-revive-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const basePath = core.getPaths().basePath;
+        const relativeDocPath = 'docs/revived-startup-note.md';
+        const relativeAssetPath = `workspaces/${workspaceId}/assets/images/revived-startup-image.png`;
+        const absoluteDocPath = path.join(basePath, relativeDocPath);
+        const absoluteAssetPath = path.join(basePath, relativeAssetPath);
+        const revivedAt = new Date('2026-03-17T12:00:00.000Z');
+        const deletedAt = '2026-03-10T08:00:00.000Z';
+        const assetBuffer = Buffer.from('revived-image-binary');
+        fs.mkdirSync(path.dirname(absoluteDocPath), { recursive: true });
+        fs.mkdirSync(path.dirname(absoluteAssetPath), { recursive: true });
+        fs.writeFileSync(absoluteDocPath, '# revived startup note\n', 'utf8');
+        fs.writeFileSync(absoluteAssetPath, assetBuffer);
+        fs.utimesSync(absoluteDocPath, revivedAt, revivedAt);
+        fs.utimesSync(absoluteAssetPath, revivedAt, revivedAt);
+        const seededStore = new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId());
+        seededStore.upsertAsset({
+            assetId: 'asset-revived-doc-1',
+            workspaceId,
+            kind: 'document',
+            originalFilename: 'revived-startup-note.md',
+            mimeType: 'text/markdown',
+            storageProvider: 'local',
+            storageKey: relativeDocPath,
+            contentSha256: 'deleted-doc-hash',
+            sizeBytes: 1,
+            documentId: 'doc-revived-startup-1',
+            referenceNumber: 33,
+            version: 4,
+            createdAt: '2026-03-01T08:00:00.000Z',
+            updatedAt: deletedAt,
+            deletedAt,
+            purgeAfter: '2026-06-01T08:00:00.000Z'
+        });
+        seededStore.upsertAsset({
+            assetId: 'asset-revived-image-1',
+            workspaceId,
+            kind: 'image',
+            originalFilename: 'revived-startup-image.png',
+            mimeType: 'image/png',
+            storageProvider: 'local',
+            storageKey: relativeAssetPath,
+            contentSha256: 'deleted-image-hash',
+            sizeBytes: 1,
+            referenceNumber: 21,
+            createdAt: '2026-03-01T08:00:00.000Z',
+            updatedAt: deletedAt,
+            deletedAt,
+            purgeAfter: '2026-06-01T08:00:00.000Z'
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const documentsMatch = matchRoute('GET', '/api/taskforce/sync/workspace/documents', routes);
+        const assetsMatch = matchRoute('GET', '/api/taskforce/sync/workspace/assets', routes);
+        const repairMatch = matchRoute('POST', '/api/taskforce/sync/workspace/repair-startup', routes);
+        expect(documentsMatch).toBeTruthy();
+        expect(assetsMatch).toBeTruthy();
+        expect(repairMatch).toBeTruthy();
+        const beforeDocumentsReq = createMockReq('GET', `/api/taskforce/sync/workspace/documents?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const beforeDocumentsRes = createMockRes();
+        await documentsMatch?.handler(beforeDocumentsReq, beforeDocumentsRes, {});
+        const beforeDocumentsBody = readJsonBody(beforeDocumentsRes);
+        const beforeDoc = (Array.isArray(beforeDocumentsBody?.documents) ? beforeDocumentsBody.documents : [])
+            .find((entry) => entry.path === relativeDocPath);
+        expect(beforeDoc).toBeUndefined();
+        const beforeAssetsReq = createMockReq('GET', `/api/taskforce/sync/workspace/assets?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const beforeAssetsRes = createMockRes();
+        await assetsMatch?.handler(beforeAssetsReq, beforeAssetsRes, {});
+        expect(readJsonBody(beforeAssetsRes).assets).toEqual([]);
+        const repairReq = createMockReq('POST', '/api/taskforce/sync/workspace/repair-startup', { workspaceId }, { 'x-taskforce-workspace-id': workspaceId });
+        const repairRes = createMockRes();
+        await repairMatch?.handler(repairReq, repairRes, {});
+        expect(readJsonBody(repairRes)).toEqual(expect.objectContaining({
+            success: true,
+            applied: 2,
+            skipped: 0,
+            failed: 0
+        }));
+        const afterDocumentsReq = createMockReq('GET', `/api/taskforce/sync/workspace/documents?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const afterDocumentsRes = createMockRes();
+        await documentsMatch?.handler(afterDocumentsReq, afterDocumentsRes, {});
+        const repairedDoc = (Array.isArray(readJsonBody(afterDocumentsRes)?.documents) ? readJsonBody(afterDocumentsRes).documents : [])
+            .find((entry) => entry.path === relativeDocPath);
+        expect(repairedDoc).toEqual(expect.objectContaining({
+            path: relativeDocPath,
+            assetId: 'asset-revived-doc-1',
+            documentId: 'doc-revived-startup-1',
+            referenceNumber: 33,
+            version: 5,
+            originalFilename: 'revived-startup-note.md'
+        }));
+        const afterAssetsReq = createMockReq('GET', `/api/taskforce/sync/workspace/assets?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const afterAssetsRes = createMockRes();
+        await assetsMatch?.handler(afterAssetsReq, afterAssetsRes, {});
+        const repairedAsset = (Array.isArray(readJsonBody(afterAssetsRes)?.assets) ? readJsonBody(afterAssetsRes).assets : [])
+            .find((entry) => entry.path === relativeAssetPath);
+        expect(repairedAsset).toEqual(expect.objectContaining({
+            path: relativeAssetPath,
+            assetId: 'asset-revived-image-1',
+            referenceNumber: 21,
+            kind: 'image',
+            mimeType: 'image/png',
+            originalFilename: 'revived-startup-image.png',
+            contentBase64: assetBuffer.toString('base64')
+        }));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const store = new WorkspaceAssetStore(reloadedCore.getDatabaseAdapter(), reloadedCore.getTenantId());
+        expect(store.get('asset-revived-doc-1', workspaceId)).toEqual(expect.objectContaining({
+            assetId: 'asset-revived-doc-1',
+            documentId: 'doc-revived-startup-1',
+            referenceNumber: 33,
+            version: 5,
+            deletedAt: null
+        }));
+        expect(store.get('asset-revived-image-1', workspaceId)).toEqual(expect.objectContaining({
+            assetId: 'asset-revived-image-1',
+            referenceNumber: 21,
+            deletedAt: null
+        }));
+    });
+    it('removes stale startup asset links to missing tasks while preserving the asset snapshot', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-repair-startup-stale-link-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const basePath = core.getPaths().basePath;
+        const relativeAssetPath = `workspaces/${workspaceId}/assets/files/stale-link-asset.txt`;
+        const absoluteAssetPath = path.join(basePath, relativeAssetPath);
+        const assetBuffer = Buffer.from('stale-link-asset');
+        fs.mkdirSync(path.dirname(absoluteAssetPath), { recursive: true });
+        fs.writeFileSync(absoluteAssetPath, assetBuffer);
+        const seededStore = new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId());
+        seededStore.upsertAsset({
+            assetId: 'asset-stale-link-1',
+            workspaceId,
+            kind: 'file',
+            originalFilename: 'stale-link-asset.txt',
+            mimeType: 'text/plain',
+            storageProvider: 'local',
+            storageKey: relativeAssetPath,
+            contentSha256: createHash('sha256').update(assetBuffer).digest('hex'),
+            sizeBytes: assetBuffer.length,
+            createdAt: '2026-03-17T11:00:00.000Z',
+            updatedAt: '2026-03-17T11:00:00.000Z'
+        });
+        seededStore.upsertLink({
+            workspaceId,
+            assetId: 'asset-stale-link-1',
+            taskId: 'task-missing-link-1',
+            role: 'attachment',
+            updatedAt: '2026-03-17T11:00:00.000Z'
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const assetsMatch = matchRoute('GET', '/api/taskforce/sync/workspace/assets', routes);
+        const repairMatch = matchRoute('POST', '/api/taskforce/sync/workspace/repair-startup', routes);
+        expect(assetsMatch).toBeTruthy();
+        expect(repairMatch).toBeTruthy();
+        const beforeAssetsReq = createMockReq('GET', `/api/taskforce/sync/workspace/assets?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const beforeAssetsRes = createMockRes();
+        await assetsMatch?.handler(beforeAssetsReq, beforeAssetsRes, {});
+        expect(beforeAssetsRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const beforeAssetsBody = readJsonBody(beforeAssetsRes);
+        const beforeAsset = (Array.isArray(beforeAssetsBody?.assets) ? beforeAssetsBody.assets : [])
+            .find((entry) => entry.path === relativeAssetPath);
+        expect(beforeAsset).toEqual(expect.objectContaining({
+            path: relativeAssetPath,
+            assetId: 'asset-stale-link-1',
+            taskId: 'task-missing-link-1',
+            linkRole: 'attachment',
+            contentBase64: assetBuffer.toString('base64')
+        }));
+        const repairReq = createMockReq('POST', '/api/taskforce/sync/workspace/repair-startup', { workspaceId }, { 'x-taskforce-workspace-id': workspaceId });
+        const repairRes = createMockRes();
+        await repairMatch?.handler(repairReq, repairRes, {});
+        expect(repairRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        expect(readJsonBody(repairRes)).toEqual(expect.objectContaining({
+            success: true,
+            applied: 1,
+            skipped: 0,
+            failed: 0
+        }));
+        const afterAssetsReq = createMockReq('GET', `/api/taskforce/sync/workspace/assets?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const afterAssetsRes = createMockRes();
+        await assetsMatch?.handler(afterAssetsReq, afterAssetsRes, {});
+        expect(afterAssetsRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const afterAssetsBody = readJsonBody(afterAssetsRes);
+        const repairedAsset = (Array.isArray(afterAssetsBody?.assets) ? afterAssetsBody.assets : [])
+            .find((entry) => entry.path === relativeAssetPath);
+        expect(repairedAsset).toEqual(expect.objectContaining({
+            path: relativeAssetPath,
+            assetId: 'asset-stale-link-1',
+            taskId: null,
+            linkRole: 'attachment',
+            contentBase64: assetBuffer.toString('base64')
+        }));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const store = new WorkspaceAssetStore(reloadedCore.getDatabaseAdapter(), reloadedCore.getTenantId());
+        expect(store.get('asset-stale-link-1', workspaceId)).toEqual(expect.objectContaining({
+            assetId: 'asset-stale-link-1',
+            storageKey: relativeAssetPath,
+            deletedAt: null
+        }));
+        expect(store.listLinksForAsset('asset-stale-link-1', workspaceId)).toEqual([]);
+        expect(store.listLinksForAsset('asset-stale-link-1', workspaceId, { includeDeleted: true })).toEqual([
+            expect.objectContaining({
+                assetId: 'asset-stale-link-1',
+                taskId: 'task-missing-link-1',
+                role: 'attachment',
+                deletedAt: expect.any(String)
+            })
+        ]);
+    });
     it('returns 400 on apply-local when workspaceId is null/empty/default', async () => {
         const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-wsmissing-');
         const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
@@ -2038,16 +2631,24 @@ describe('Server Routes Workspace Sync Integration', () => {
     it('keeps repeated document scans correct and invalidates cache when file content changes', async () => {
         const projectRoot = createIsolatedProjectRoot('taskforce-sync-doc-cache-');
         const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const basePath = core.getPaths().basePath;
         core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
-        const syncRoot = core.getPaths().basePath;
-        const docsDir = path.join(syncRoot, 'docs');
-        fs.mkdirSync(docsDir, { recursive: true });
-        const relativeDocPath = 'docs/cache-target.md';
-        const absoluteDocPath = path.join(syncRoot, relativeDocPath);
-        fs.writeFileSync(absoluteDocPath, '# cache test\n', 'utf8');
         const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const uploadMatch = matchRoute('POST', '/api/taskforce/context-upload', routes);
         const match = matchRoute('GET', '/api/taskforce/sync/workspace/documents', routes);
+        expect(uploadMatch).toBeTruthy();
         expect(match).toBeTruthy();
+        const uploadReq = createMockReq('POST', '/api/taskforce/context-upload', {
+            file: `data:text/markdown;base64,${Buffer.from('# cache test\n', 'utf8').toString('base64')}`,
+            originalName: 'cache-target.md',
+            workspaceId
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const uploadRes = createMockRes();
+        await uploadMatch?.handler(uploadReq, uploadRes, {});
+        expect(uploadRes.writeHead).toHaveBeenCalledWith(200, { 'Content-Type': 'application/json' });
+        const uploadBody = JSON.parse(String(uploadRes.end.mock.calls.at(-1)?.[0] || '{}'));
+        const relativeDocPath = String(uploadBody?.fsPath || '');
+        const absoluteDocPath = path.join(basePath, relativeDocPath);
         const req1 = createMockReq('GET', `/api/taskforce/sync/workspace/documents?workspaceId=${workspaceId}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
         const res1 = createMockRes();
         await match?.handler(req1, res1, {});
@@ -2102,6 +2703,24 @@ describe('Server Routes Workspace Sync Integration', () => {
         expect(doc).toBeTruthy();
         expect(doc.content).toBe('# local attachment\n');
     });
+    it('does not sync raw docs directory markdown files because shared document sync must be canonical and workspace-scoped', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-exclude-raw-docs-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const rawDocsDir = path.join(core.getPaths().basePath, 'docs');
+        fs.mkdirSync(rawDocsDir, { recursive: true });
+        fs.writeFileSync(path.join(rawDocsDir, 'legacy-shared.md'), '# legacy shared doc\n', 'utf8');
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const documentsMatch = matchRoute('GET', '/api/taskforce/sync/workspace/documents', routes);
+        expect(documentsMatch).toBeTruthy();
+        const req = createMockReq('GET', `/api/taskforce/sync/workspace/documents?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await documentsMatch?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const body = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+        const docs = Array.isArray(body?.documents) ? body.documents : [];
+        expect(docs.some((entry) => entry.path === 'docs/legacy-shared.md')).toBe(false);
+    });
     it('converges task conflicts deterministically for equal timestamps regardless of apply order', async () => {
         const applySequence = async (prefix, titlesInOrder) => {
             const projectRoot = createIsolatedProjectRoot(prefix);