@taskforcehq/taskforce 0.3.306 → 0.3.308

package/dist/server/aiProfileAvatarAssets.js

@@ -0,0 +1,319 @@
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { normalizeTaskDataRelativePath } from '../storage/objectStorageClient.js';
+const SUPPORTED_IMAGE_MIME_TYPES = new Set([
+    'image/gif',
+    'image/jpeg',
+    'image/png',
+    'image/webp',
+]);
+const AVATAR_MAX_BYTES = 5 * 1024 * 1024;
+function normalizeId(value) {
+    return String(value || '').trim();
+}
+function sanitizeStorageSegment(value, fallback) {
+    const normalized = normalizeId(value)
+        .replace(/[^a-zA-Z0-9._-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return normalized || fallback;
+}
+function normalizeImageMimeType(value) {
+    return normalizeId(value).toLowerCase();
+}
+function extensionForMimeType(mimeType) {
+    if (mimeType === 'image/gif')
+        return 'gif';
+    if (mimeType === 'image/jpeg')
+        return 'jpg';
+    if (mimeType === 'image/png')
+        return 'png';
+    return 'webp';
+}
+function stableAssetId(workspaceId, profileId, slot) {
+    const digest = createHash('sha256')
+        .update(`${workspaceId}:${profileId}:${slot}`)
+        .digest('hex')
+        .slice(0, 32);
+    return `asset-${digest}`;
+}
+export function buildAiProfileAvatarStorageKey(input) {
+    const workspaceId = sanitizeStorageSegment(input.workspaceId, 'default');
+    const profileId = sanitizeStorageSegment(input.profileId, 'ai-profile');
+    const ext = extensionForMimeType(input.mimeType);
+    return `workspaces/${workspaceId}/assets/images/ai-profiles/${profileId}/avatar/${input.slot}.${ext}`;
+}
+function contextUrlForStorageKey(storageKey) {
+    return `/api/taskforce/context/${encodeURIComponent(storageKey)}`;
+}
+export function storageKeyFromContextUrl(url) {
+    const raw = normalizeId(url);
+    if (!raw)
+        return null;
+    const contextPrefix = '/api/taskforce/context/';
+    if (!raw.startsWith(contextPrefix))
+        return null;
+    const encodedPath = raw.slice(contextPrefix.length).split('?')[0] || '';
+    try {
+        return normalizeTaskDataRelativePath(decodeURIComponent(encodedPath));
+    }
+    catch {
+        return null;
+    }
+}
+function validatePayload(payload, label) {
+    const mimeType = normalizeImageMimeType(payload.mimeType);
+    if (!SUPPORTED_IMAGE_MIME_TYPES.has(mimeType)) {
+        throw new Error(`${label} must be a PNG, JPEG, WebP, or GIF image.`);
+    }
+    if (!Buffer.isBuffer(payload.buffer) || payload.buffer.length === 0) {
+        throw new Error(`${label} is empty.`);
+    }
+    if (payload.buffer.length > AVATAR_MAX_BYTES) {
+        throw new Error(`${label} must be 5 MB or smaller.`);
+    }
+    return mimeType;
+}
+function storageKeyBelongsToAiProfileAvatar(workspaceId, profileId, storageKey) {
+    const workspaceIdSafe = sanitizeStorageSegment(workspaceId, 'default');
+    const profileIdSafe = sanitizeStorageSegment(profileId, 'ai-profile');
+    return storageKey.startsWith(`workspaces/${workspaceIdSafe}/assets/images/ai-profiles/${profileIdSafe}/avatar/`);
+}
+async function writeAvatarObject(deps, storageKey, payload, provider) {
+    if (provider === 'r2') {
+        const objectStorageClient = deps.getObjectStorageClient();
+        if (!objectStorageClient)
+            throw new Error('Object storage is not configured.');
+        await objectStorageClient.putObject(storageKey, payload.buffer, payload.mimeType);
+        return;
+    }
+    const { basePath } = deps.core.getPaths();
+    const destination = deps.ensureWithinDir(path.join(basePath, storageKey), basePath);
+    if (!destination)
+        throw new Error('Invalid AI profile avatar storage path.');
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.writeFileSync(destination, payload.buffer);
+}
+async function deleteAvatarObject(deps, storageKey, provider) {
+    try {
+        deps.markAssetDeleted(storageKey);
+    }
+    catch {
+        // Best-effort legacy asset index cleanup should not make the canonical
+        // workspace asset/profile update fail after the new slots are written.
+    }
+    if (provider === 'r2') {
+        const objectStorageClient = deps.getObjectStorageClient();
+        if (objectStorageClient) {
+            await objectStorageClient.deleteObject(storageKey).catch(() => false);
+        }
+        return;
+    }
+    const { basePath } = deps.core.getPaths();
+    const destination = deps.ensureWithinDir(path.join(basePath, storageKey), basePath);
+    if (destination && fs.existsSync(destination)) {
+        fs.rmSync(destination, { force: true });
+    }
+}
+function upsertAvatarAsset(input) {
+    if (!input.deps.workspaceAssetStore) {
+        throw new Error('Workspace asset storage is required for AI profile avatars.');
+    }
+    const contentSha256 = createHash('sha256').update(input.payload.buffer).digest('hex');
+    const existing = input.deps.workspaceAssetStore.getByStorageKey(input.storageKey, input.workspaceId);
+    return input.deps.workspaceAssetStore.upsertAsset({
+        assetId: existing?.assetId || stableAssetId(input.workspaceId, input.profileId, input.slot),
+        workspaceId: input.workspaceId,
+        kind: 'image',
+        logicalName: `AI profile avatar ${input.slot}`,
+        originalFilename: normalizeId(input.payload.originalName) || `${input.slot}.${extensionForMimeType(input.payload.mimeType)}`,
+        mimeType: input.payload.mimeType,
+        storageProvider: input.provider,
+        storageKey: input.storageKey,
+        contentSha256,
+        sizeBytes: input.payload.buffer.length,
+        documentId: null,
+        version: null,
+        isLatest: true,
+        scanStatus: 'clean',
+        scanEngine: null,
+        scanDetails: null,
+        createdByUserId: existing?.createdByUserId || normalizeId(input.actorId) || null,
+        createdAt: existing?.createdAt || input.nowIso,
+        updatedAt: input.nowIso,
+        deletedAt: null,
+        purgeAfter: null,
+    });
+}
+async function cleanupAiProfileAvatarAssets(input) {
+    const keep = new Set(Array.from(input.keepStorageKeys || []).filter(Boolean));
+    const candidates = new Map();
+    for (const storageKey of input.explicitStorageKeys || []) {
+        const normalized = normalizeTaskDataRelativePath(normalizeId(storageKey));
+        if (!normalized || keep.has(normalized))
+            continue;
+        if (storageKeyBelongsToAiProfileAvatar(input.workspaceId, input.profileId, normalized)) {
+            candidates.set(normalized, input.providerFallback);
+        }
+    }
+    if (input.deps.workspaceAssetStore) {
+        const assets = input.deps.workspaceAssetStore.listAllByWorkspace(input.workspaceId, {
+            includeDeleted: false,
+            kind: 'image',
+        });
+        for (const asset of assets) {
+            if (!storageKeyBelongsToAiProfileAvatar(input.workspaceId, input.profileId, asset.storageKey))
+                continue;
+            if (keep.has(asset.storageKey))
+                continue;
+            candidates.set(asset.storageKey, asset.storageProvider === 'r2' ? 'r2' : 'local');
+        }
+    }
+    for (const [storageKey, provider] of candidates) {
+        try {
+            const asset = input.deps.workspaceAssetStore?.getByStorageKey(storageKey, input.workspaceId);
+            if (asset && !asset.deletedAt) {
+                input.deps.workspaceAssetStore?.markDeleted(asset.assetId, input.workspaceId);
+            }
+        }
+        catch {
+            input.deps.appendStorageTelemetry('ai_avatar.cleanup', {
+                path: storageKey,
+                provider,
+                status: 'metadata-delete-failed',
+            });
+        }
+        try {
+            await deleteAvatarObject(input.deps, storageKey, provider);
+            input.deps.appendStorageTelemetry('ai_avatar.cleanup', {
+                path: storageKey,
+                provider,
+                status: 'deleted',
+            });
+        }
+        catch {
+            input.deps.appendStorageTelemetry('ai_avatar.cleanup', {
+                path: storageKey,
+                provider,
+                status: 'object-delete-failed',
+            });
+        }
+    }
+}
+export async function saveAiProfileAvatarAssets(deps, input) {
+    const workspaceId = normalizeId(input.workspaceId);
+    const profileId = normalizeId(input.profileId);
+    if (!workspaceId)
+        throw new Error('workspaceId is required.');
+    if (!profileId)
+        throw new Error('profileId is required.');
+    const existingProfile = deps.core.listAiProfiles(workspaceId)
+        .find((profile) => profile.id === profileId);
+    if (!existingProfile)
+        throw new Error(`Profile ${profileId} not found.`);
+    const displayMimeType = validatePayload(input.display, 'Display avatar');
+    const sourcePayload = input.source || input.display;
+    const sourceMimeType = validatePayload(sourcePayload, 'Source avatar');
+    const displayPayload = { ...input.display, mimeType: displayMimeType };
+    const normalizedSourcePayload = { ...sourcePayload, mimeType: sourceMimeType };
+    const displayStorageKey = buildAiProfileAvatarStorageKey({
+        workspaceId,
+        profileId,
+        slot: 'display',
+        mimeType: displayMimeType,
+    });
+    const sourceStorageKey = buildAiProfileAvatarStorageKey({
+        workspaceId,
+        profileId,
+        slot: 'source',
+        mimeType: sourceMimeType,
+    });
+    const objectStorageClient = deps.getObjectStorageClient();
+    const provider = objectStorageClient ? 'r2' : 'local';
+    const nowIso = new Date().toISOString();
+    await writeAvatarObject(deps, displayStorageKey, displayPayload, provider);
+    await writeAvatarObject(deps, sourceStorageKey, normalizedSourcePayload, provider);
+    const displayAsset = upsertAvatarAsset({
+        deps,
+        workspaceId,
+        profileId,
+        slot: 'display',
+        storageKey: displayStorageKey,
+        payload: displayPayload,
+        provider,
+        actorId: input.actorId,
+        nowIso,
+    });
+    const sourceAsset = upsertAvatarAsset({
+        deps,
+        workspaceId,
+        profileId,
+        slot: 'source',
+        storageKey: sourceStorageKey,
+        payload: normalizedSourcePayload,
+        provider,
+        actorId: input.actorId,
+        nowIso,
+    });
+    deps.core.notifyDocumentMetadataMutation(workspaceId, [displayStorageKey, sourceStorageKey], 'upsert');
+    deps.appendStorageTelemetry('ai_avatar.upload', {
+        path: displayStorageKey,
+        provider,
+        status: 'stored',
+    });
+    const profile = deps.core.updateAiProfileAvatar({
+        workspaceId,
+        profileId,
+        avatarUrl: contextUrlForStorageKey(displayStorageKey),
+        avatarSourceUrl: contextUrlForStorageKey(sourceStorageKey),
+    });
+    await cleanupAiProfileAvatarAssets({
+        deps,
+        workspaceId,
+        profileId,
+        keepStorageKeys: [displayStorageKey, sourceStorageKey],
+        explicitStorageKeys: [
+            storageKeyFromContextUrl(existingProfile.avatarUrl),
+            storageKeyFromContextUrl(existingProfile.avatarSourceUrl),
+        ],
+        providerFallback: provider,
+    });
+    return {
+        profile,
+        displayAsset,
+        sourceAsset,
+        displayStorageKey,
+        sourceStorageKey,
+    };
+}
+export async function clearAiProfileAvatarAssets(deps, input) {
+    const workspaceId = normalizeId(input.workspaceId);
+    const profileId = normalizeId(input.profileId);
+    if (!workspaceId)
+        throw new Error('workspaceId is required.');
+    if (!profileId)
+        throw new Error('profileId is required.');
+    const existingProfile = deps.core.listAiProfiles(workspaceId)
+        .find((profile) => profile.id === profileId);
+    const objectStorageClient = deps.getObjectStorageClient();
+    const provider = objectStorageClient ? 'r2' : 'local';
+    const profile = deps.core.updateAiProfileAvatar({
+        workspaceId,
+        profileId,
+        avatarUrl: null,
+        avatarSourceUrl: null,
+    });
+    await cleanupAiProfileAvatarAssets({
+        deps,
+        workspaceId,
+        profileId,
+        keepStorageKeys: [],
+        explicitStorageKeys: [
+            storageKeyFromContextUrl(existingProfile?.avatarUrl),
+            storageKeyFromContextUrl(existingProfile?.avatarSourceUrl),
+        ],
+        providerFallback: provider,
+    });
+    return { profile };
+}

package/dist/server/aiProfileAvatarAssets.test.d.ts

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

package/dist/server/aiProfileAvatarAssets.test.js

@@ -0,0 +1,213 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { TaskforceCore } from '../core/Taskforce';
+import { WorkspaceAssetStore } from '../storage/workspaceAssetStore';
+import { buildAiProfileAvatarStorageKey, saveAiProfileAvatarAssets, } from './aiProfileAvatarAssets';
+const roots = [];
+function createFixture() {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-ai-avatar-assets-'));
+    roots.push(projectRoot);
+    const core = new TaskforceCore({ projectRoot });
+    const workspaceAssetStore = new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId());
+    const ensureWithinDir = (candidatePath, rootDir) => {
+        const resolvedRoot = path.resolve(rootDir);
+        const resolvedCandidate = path.resolve(candidatePath);
+        return resolvedCandidate.startsWith(resolvedRoot) ? resolvedCandidate : null;
+    };
+    return {
+        core,
+        workspaceAssetStore,
+        deps: {
+            core,
+            workspaceAssetStore,
+            getObjectStorageClient: () => null,
+            ensureWithinDir,
+            markAssetDeleted: vi.fn(),
+            appendStorageTelemetry: vi.fn(),
+        }
+    };
+}
+afterEach(() => {
+    while (roots.length > 0) {
+        const root = roots.pop();
+        if (root)
+            fs.rmSync(root, { recursive: true, force: true });
+    }
+});
+describe('AI profile avatar stable assets', () => {
+    it('builds deterministic stable slot paths', () => {
+        expect(buildAiProfileAvatarStorageKey({
+            workspaceId: 'workspace-1',
+            profileId: 'ai-profile-1',
+            slot: 'display',
+            mimeType: 'image/webp',
+        })).toBe('workspaces/workspace-1/assets/images/ai-profiles/ai-profile-1/avatar/display.webp');
+        expect(buildAiProfileAvatarStorageKey({
+            workspaceId: 'workspace-1',
+            profileId: 'ai-profile-1',
+            slot: 'source',
+            mimeType: 'image/gif',
+        })).toBe('workspaces/workspace-1/assets/images/ai-profiles/ai-profile-1/avatar/source.gif');
+    });
+    it('overwrites the same display/source assets and advances profile revision', async () => {
+        const { core, workspaceAssetStore, deps } = createFixture();
+        const workspaceId = 'workspace-1';
+        const resolved = core.resolveAiProfile({
+            workspaceId,
+            name: 'Codex',
+            provider: 'OpenAI',
+            model: 'gpt-5',
+        });
+        const profileId = resolved.profile.id;
+        const first = await saveAiProfileAvatarAssets(deps, {
+            workspaceId,
+            profileId,
+            display: {
+                buffer: Buffer.from('display-one'),
+                mimeType: 'image/webp',
+                originalName: 'display.webp',
+            },
+            source: {
+                buffer: Buffer.from('source-one'),
+                mimeType: 'image/jpeg',
+                originalName: 'source.jpg',
+            },
+            actorId: 'user-1',
+        });
+        const second = await saveAiProfileAvatarAssets(deps, {
+            workspaceId,
+            profileId,
+            display: {
+                buffer: Buffer.from('display-two'),
+                mimeType: 'image/webp',
+                originalName: 'display.webp',
+            },
+            source: {
+                buffer: Buffer.from('source-two'),
+                mimeType: 'image/jpeg',
+                originalName: 'source.jpg',
+            },
+            actorId: 'user-1',
+        });
+        expect(second.displayStorageKey).toBe(first.displayStorageKey);
+        expect(second.sourceStorageKey).toBe(first.sourceStorageKey);
+        expect(second.profile.avatarRevision).toBe(2);
+        expect(second.profile.avatarUrl).toBe(`/api/taskforce/context/${encodeURIComponent(second.displayStorageKey)}`);
+        expect(second.profile.avatarSourceUrl).toBe(`/api/taskforce/context/${encodeURIComponent(second.sourceStorageKey)}`);
+        const assets = workspaceAssetStore.listAllByWorkspace(workspaceId, { kind: 'image' });
+        expect(assets.map((asset) => asset.storageKey).sort()).toEqual([
+            second.displayStorageKey,
+            second.sourceStorageKey,
+        ].sort());
+        const displayAsset = workspaceAssetStore.getByStorageKey(second.displayStorageKey, workspaceId);
+        expect(displayAsset?.contentSha256).not.toBe(first.displayAsset.contentSha256);
+        const displayPath = path.join(core.getPaths().basePath, second.displayStorageKey);
+        expect(fs.readFileSync(displayPath, 'utf8')).toBe('display-two');
+        core.close();
+    });
+    it('tombstones old generated avatar assets after a stable replacement succeeds', async () => {
+        const { core, workspaceAssetStore, deps } = createFixture();
+        const workspaceId = 'workspace-1';
+        const resolved = core.resolveAiProfile({
+            workspaceId,
+            name: 'Harry Palmer',
+            provider: 'OpenClaw',
+            model: 'gpt-5.4',
+        });
+        const profileId = resolved.profile.id;
+        const oldStorageKey = `workspaces/${workspaceId}/assets/images/ai-profiles/${profileId}/avatar/asset-old-cropped-harry.webp`;
+        fs.mkdirSync(path.dirname(path.join(core.getPaths().basePath, oldStorageKey)), { recursive: true });
+        fs.writeFileSync(path.join(core.getPaths().basePath, oldStorageKey), 'old-avatar');
+        workspaceAssetStore.upsertAsset({
+            assetId: 'asset-old-harry-avatar-000000000001',
+            workspaceId,
+            kind: 'image',
+            logicalName: 'old avatar',
+            originalFilename: 'cropped-harry.webp',
+            mimeType: 'image/webp',
+            storageProvider: 'local',
+            storageKey: oldStorageKey,
+            contentSha256: 'old-sha',
+            sizeBytes: 10,
+        });
+        core.updateAiProfileAvatar({
+            workspaceId,
+            profileId,
+            avatarUrl: `/api/taskforce/context/${encodeURIComponent(oldStorageKey)}`,
+            avatarSourceUrl: null,
+        });
+        await saveAiProfileAvatarAssets(deps, {
+            workspaceId,
+            profileId,
+            display: {
+                buffer: Buffer.from('display'),
+                mimeType: 'image/webp',
+                originalName: 'display.webp',
+            },
+            source: {
+                buffer: Buffer.from('source'),
+                mimeType: 'image/webp',
+                originalName: 'source.webp',
+            },
+        });
+        expect(workspaceAssetStore.getByStorageKey(oldStorageKey, workspaceId)?.deletedAt).toBeTruthy();
+        expect(fs.existsSync(path.join(core.getPaths().basePath, oldStorageKey))).toBe(false);
+        expect(deps.markAssetDeleted).toHaveBeenCalledWith(oldStorageKey);
+        core.close();
+    });
+    it('does not fail a stable replacement when legacy cleanup markers fail', async () => {
+        const { core, workspaceAssetStore, deps } = createFixture();
+        const workspaceId = 'workspace-1';
+        const resolved = core.resolveAiProfile({
+            workspaceId,
+            name: 'Control',
+            provider: 'OpenAI',
+            model: 'gpt-5',
+        });
+        const profileId = resolved.profile.id;
+        const oldStorageKey = `workspaces/${workspaceId}/assets/images/ai-profiles/${profileId}/avatar/asset-old-control.webp`;
+        fs.mkdirSync(path.dirname(path.join(core.getPaths().basePath, oldStorageKey)), { recursive: true });
+        fs.writeFileSync(path.join(core.getPaths().basePath, oldStorageKey), 'old-avatar');
+        workspaceAssetStore.upsertAsset({
+            assetId: 'asset-old-control-avatar-0000001',
+            workspaceId,
+            kind: 'image',
+            logicalName: 'old avatar',
+            originalFilename: 'control.webp',
+            mimeType: 'image/webp',
+            storageProvider: 'local',
+            storageKey: oldStorageKey,
+            contentSha256: 'old-sha',
+            sizeBytes: 10,
+        });
+        core.updateAiProfileAvatar({
+            workspaceId,
+            profileId,
+            avatarUrl: `/api/taskforce/context/${encodeURIComponent(oldStorageKey)}`,
+            avatarSourceUrl: null,
+        });
+        deps.markAssetDeleted.mockImplementation(() => {
+            throw new Error('legacy marker failed');
+        });
+        const result = await saveAiProfileAvatarAssets(deps, {
+            workspaceId,
+            profileId,
+            display: {
+                buffer: Buffer.from('display'),
+                mimeType: 'image/webp',
+                originalName: 'display.webp',
+            },
+            source: {
+                buffer: Buffer.from('source'),
+                mimeType: 'image/webp',
+                originalName: 'source.webp',
+            },
+        });
+        expect(result.profile.avatarUrl).toBe(`/api/taskforce/context/${encodeURIComponent(result.displayStorageKey)}`);
+        expect(workspaceAssetStore.getByStorageKey(oldStorageKey, workspaceId)?.deletedAt).toBeTruthy();
+        expect(fs.existsSync(path.join(core.getPaths().basePath, oldStorageKey))).toBe(false);
+        core.close();
+    });
+});

package/dist/server/annotatedAttachmentsRoutes.test.js

@@ -199,7 +199,69 @@ describe('annotated attachment routes', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
-    it('allows local mutation attribution fallback when local runtime has an active user even if auth is enabled', async () => {
+    it('lists canonical image assets for the Image Notes tray', async () => {
+        const projectRoot = createProjectRoot();
+        const core = new TaskforceCore({
+            projectRoot,
+            storagePath: path.join(projectRoot, '.taskforce'),
+        });
+        try {
+            core.createWorkspace({ workspaceId: 'workspace-1', name: 'Workspace 1' });
+            const category = core.getCategories()[0]?.value;
+            const type = core.getTypes()[0]?.value;
+            const task = core.createTask({ title: 'Review image', category, type }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            const assetStore = core.getWorkspaceAssetStore();
+            const asset = assetStore.upsertAsset({
+                assetId: 'asset-image-1',
+                workspaceId: 'workspace-1',
+                kind: 'image',
+                originalFilename: 'ui-review.png',
+                logicalName: 'UI Review',
+                mimeType: 'image/png',
+                storageProvider: 'local',
+                storageKey: 'workspaces/workspace-1/assets/images/asset-image-1-ui-review.png',
+                contentSha256: 'sha-image-1',
+                sizeBytes: 256,
+            });
+            assetStore.upsertLink({
+                workspaceId: 'workspace-1',
+                assetId: asset.assetId,
+                taskId: task.id,
+                role: 'attachment',
+            });
+            core.createAnnotatedAttachmentSession({
+                workspaceId: 'workspace-1',
+                taskId: '',
+                baseImageAssetId: asset.assetId,
+                title: 'UI Review session',
+                actorId: 'owner-1',
+            });
+            const routes = createRoutes(core);
+            const listImagesMatch = matchRoute('GET', '/api/taskforce/annotated-attachments/images', routes);
+            const listImagesReq = createMockReq('GET', '/api/taskforce/annotated-attachments/images?workspaceId=workspace-1');
+            const listImagesRes = createMockRes();
+            await listImagesMatch?.handler(listImagesReq, listImagesRes, {});
+            expect(listImagesRes.statusCode).toBe(200);
+            expect(listImagesRes.getHeader('cache-control')).toBe('no-store');
+            const listed = JSON.parse(listImagesRes.__getBody());
+            expect(listed.images).toHaveLength(1);
+            expect(listed.images[0]).toMatchObject({
+                assetId: asset.assetId,
+                displayName: 'UI Review',
+                path: '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Fimages%2Fasset-image-1-ui-review.png',
+                attachmentCount: 1,
+                sessionCount: 1,
+                taskId: task.id,
+                taskReferenceLabel: task.referenceLabel,
+            });
+            expect(listed.images[0].imageReferenceLabel).toMatch(/^I-\d+$/);
+        }
+        finally {
+            core.close();
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('rejects local mutation attribution when only an active workspace user fallback is available', async () => {
         const projectRoot = createProjectRoot();
         const core = new TaskforceCore({
             projectRoot,
@@ -252,13 +314,10 @@ describe('annotated attachment routes', () => {
             });
             const createRes = createMockRes();
             await createMatch?.handler(createReq, createRes, {});
-            expect(createRes.statusCode).toBe(200);
+            expect(createRes.statusCode).toBe(401);
             expect(JSON.parse(createRes.__getBody())).toMatchObject({
-                success: true,
-                session: expect.objectContaining({
-                    createdByActorId: 'user-local-1',
-                    updatedByActorId: 'user-local-1',
-                }),
+                success: false,
+                code: 'MUTATION_AUTH_REQUIRED',
             });
         }
         finally {

package/dist/server/index.js

@@ -254,6 +254,10 @@ export function resolveMaxPayloadBytesForPath(pathname, defaultMaxBytes) {
         // Sync routes (especially applying local changes) often include large binary attachments
         return Math.max(defaultMaxBytes, 50 * 1024 * 1024);
     }
+    if (pathname === '/api/taskforce/ui-state') {
+        // Workspace-sync UI state can carry large baselines; keep the global guard aligned with its route parser.
+        return Math.max(defaultMaxBytes, 50 * 1024 * 1024);
+    }
     return defaultMaxBytes;
 }
 export function shouldRewriteSetCookieForLocalDevHost(hostHeader) {

package/dist/server/index.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { ensureBillingWebhookAuthExclusion, ensurePublicSiteConfigAuthExclusion, configureHttpServerTimeouts, isBillingWebhookPath, rewriteProxySetCookieForLocalHost, resolveHttpServerTimeoutSettings, resolveEffectiveRequestUserId, resolveAuthorizedWorkspaceAccess, resolveDisabledAccessError, shouldApplyReadOnlyMutationGuard, shouldRewriteProxySetCookieDomain, shouldApplyAuthRateLimitForPath, shouldProxyCloudPath, writeJsonErrorIfPossible } from './index.js';
+import { ensureBillingWebhookAuthExclusion, ensurePublicSiteConfigAuthExclusion, configureHttpServerTimeouts, isBillingWebhookPath, rewriteProxySetCookieForLocalHost, resolveHttpServerTimeoutSettings, resolveEffectiveRequestUserId, resolveAuthorizedWorkspaceAccess, resolveDisabledAccessError, resolveMaxPayloadBytesForPath, shouldApplyReadOnlyMutationGuard, shouldRewriteProxySetCookieDomain, shouldApplyAuthRateLimitForPath, shouldProxyCloudPath, writeJsonErrorIfPossible } from './index.js';
 describe('server index helper policies', () => {
     it('uses proxy-friendly HTTP server timeouts by default', () => {
         const settings = resolveHttpServerTimeoutSettings({});
@@ -60,6 +60,11 @@ describe('server index helper policies', () => {
         expect(shouldApplyAuthRateLimitForPath('/api/taskforce/auth/session')).toBe(false);
         expect(shouldApplyAuthRateLimitForPath('/api/taskforce/billing/webhook')).toBe(false);
     });
+    it('allows workspace sync-sized ui-state payloads through the global guard', () => {
+        expect(resolveMaxPayloadBytesForPath('/api/taskforce/ui-state', 1_048_576)).toBe(50 * 1024 * 1024);
+        expect(resolveMaxPayloadBytesForPath('/api/taskforce/sync/workspace/push', 1_048_576)).toBe(50 * 1024 * 1024);
+        expect(resolveMaxPayloadBytesForPath('/api/taskforce/task', 1_048_576)).toBe(1_048_576);
+    });
     it('writes a json error when headers are still available', () => {
         let headersSent = false;
         let writableEnded = false;