@taskforcehq/taskforce 0.3.170 → 0.3.300

package/dist/mcp/runtime.test.js

@@ -0,0 +1,3293 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { createTaskforceMcpServer } from './runtime';
+import { MCP_TOOL_REGISTRY } from './toolRegistry';
+import { TaskforceCore, TaskforceRuleError } from '../core/Taskforce';
+import { WorkspaceAssetStore } from '../storage/workspaceAssetStore';
+import { ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY, APP_GATE_DEFINITIONS, } from '../runtime/appGates';
+function createProjectRoot() {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-mcp-runtime-'));
+    const core = new TaskforceCore({
+        projectRoot,
+        storagePath: path.join(projectRoot, '.taskforce')
+    });
+    try {
+        Object.defineProperty(core, 'getAccountAccessStatus', {
+            configurable: true,
+            value: () => ({
+                gate: 'ok',
+                hasEntitlement: true,
+                canAccessApp: true,
+                canAccessPlans: true,
+                signupMonetizationStrategy: 'none',
+                planSelectionRequired: false,
+                message: null,
+                entitlement: null
+            })
+        });
+        core.createWorkspace({ workspaceId: 'workspace-1', name: 'Workspace 1' });
+        core.ensureBootstrapUserAccess({
+            userId: 'owner-1',
+            workspaceId: 'workspace-1',
+            role: 'owner',
+            email: 'owner-1@example.com'
+        });
+    }
+    finally {
+        core.close();
+    }
+    return projectRoot;
+}
+async function listTools(projectRoot, runtimeMode) {
+    const runtime = createTaskforceMcpServer({
+        projectRoot,
+        runtimeMode,
+        logStartup: false,
+        auth: runtimeMode === 'cloud'
+            ? { scopes: ['tasks:read', 'tasks:write', 'workspace:read'] }
+            : undefined
+    });
+    const handler = runtime.server._requestHandlers.get('tools/list');
+    if (!handler) {
+        throw new Error('tools/list handler not registered');
+    }
+    return await handler({
+        jsonrpc: '2.0',
+        id: 'test-tools-list',
+        method: 'tools/list',
+        params: {}
+    }, {});
+}
+async function callTool(projectRoot, runtimeMode, name, args, options) {
+    const runtime = createTaskforceMcpServer({
+        projectRoot,
+        runtimeMode,
+        workspaceId: options?.workspaceId,
+        logStartup: false,
+        auth: runtimeMode === 'cloud'
+            ? {
+                scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
+                userId: options?.authUserId || 'owner-1',
+                actorType: 'oauth',
+                aiProfileToken: options?.authAiProfileToken || null,
+                aiProfileName: options?.authAiProfileName || null,
+                aiProfileDescription: options?.authAiProfileDescription || null,
+                aiProfileRole: options?.authAiProfileRole || null,
+                aiProfileProvider: options?.authAiProfileProvider || null,
+                aiProfileModel: options?.authAiProfileModel || null,
+                aiProfileSurfaceType: options?.authAiProfileSurfaceType || null,
+            }
+            : undefined
+    });
+    const handler = runtime.server._requestHandlers.get('tools/call');
+    if (!handler) {
+        throw new Error('tools/call handler not registered');
+    }
+    if (name !== 'resolve_profile' && options?.resolveProfile !== false && MCP_TOOL_REGISTRY[name]?.mutating) {
+        await handler({
+            jsonrpc: '2.0',
+            id: 'test-tools-call-bootstrap-resolve-profile',
+            method: 'tools/call',
+            params: {
+                name: 'resolve_profile',
+                arguments: {
+                    name: 'Codex',
+                    icon: 'Bot',
+                    color: '#ef6c00'
+                }
+            }
+        }, {});
+    }
+    return await handler({
+        jsonrpc: '2.0',
+        id: `test-tools-call-${name}`,
+        method: 'tools/call',
+        params: {
+            name,
+            arguments: args
+        }
+    }, {});
+}
+async function readResource(projectRoot, runtimeMode, uri, options) {
+    const runtime = createTaskforceMcpServer({
+        projectRoot,
+        runtimeMode,
+        workspaceId: options?.workspaceId,
+        logStartup: false,
+        auth: runtimeMode === 'cloud'
+            ? {
+                scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
+                userId: options?.authUserId || 'owner-1',
+                actorType: 'oauth'
+            }
+            : undefined
+    });
+    const handler = runtime.server._requestHandlers.get('resources/read');
+    if (!handler) {
+        throw new Error('resources/read handler not registered');
+    }
+    return await handler({
+        jsonrpc: '2.0',
+        id: `test-resources-read-${uri}`,
+        method: 'resources/read',
+        params: { uri }
+    }, {});
+}
+async function listResources(projectRoot, runtimeMode, options) {
+    const runtime = createTaskforceMcpServer({
+        projectRoot,
+        runtimeMode,
+        workspaceId: options?.workspaceId,
+        logStartup: false,
+        auth: runtimeMode === 'cloud'
+            ? {
+                scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
+                userId: options?.authUserId || 'owner-1',
+                actorType: 'oauth'
+            }
+            : undefined
+    });
+    const handler = runtime.server._requestHandlers.get('resources/list');
+    if (!handler) {
+        throw new Error('resources/list handler not registered');
+    }
+    return await handler({
+        jsonrpc: '2.0',
+        id: 'test-resources-list',
+        method: 'resources/list',
+        params: {}
+    }, {});
+}
+function getTool(result, name) {
+    const tool = result.tools.find((entry) => entry.name === name);
+    expect(tool).toBeDefined();
+    return tool;
+}
+function parseToolJson(result) {
+    const text = result.content?.[0]?.text;
+    expect(text).toBeTruthy();
+    return JSON.parse(String(text));
+}
+function seedAnnotatedAttachmentFixture(projectRoot) {
+    const core = new TaskforceCore({
+        projectRoot,
+        storagePath: path.join(projectRoot, '.taskforce')
+    });
+    try {
+        const category = core.getCategories()[0]?.value;
+        const type = core.getTypes()[0]?.value;
+        const task = core.createTask({
+            title: 'Annotated attachment fixture',
+            category,
+            type
+        }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+        const assetStore = core.getWorkspaceAssetStore();
+        assetStore.upsertAsset({
+            assetId: 'asset-annotated-1',
+            workspaceId: 'workspace-1',
+            kind: 'image',
+            logicalName: 'Fixture image',
+            originalFilename: 'fixture.png',
+            mimeType: 'image/png',
+            storageProvider: 'local',
+            storageKey: 'workspaces/workspace-1/assets/images/asset-annotated-1-fixture.png',
+            contentSha256: 'sha-annotated-1',
+            sizeBytes: 512,
+        });
+        assetStore.upsertLink({
+            workspaceId: 'workspace-1',
+            assetId: 'asset-annotated-1',
+            taskId: task.id,
+            role: 'attachment',
+        });
+        const session = core.createAnnotatedAttachmentSession({
+            workspaceId: 'workspace-1',
+            taskId: task.id,
+            baseImageAssetId: 'asset-annotated-1',
+            title: 'Fixture session',
+            globalInstruction: 'Answer each annotation in order.',
+            actorId: 'owner-1',
+            annotations: [
+                {
+                    id: 'annotation-1',
+                    kind: 'pin',
+                    order: 0,
+                    markerType: 'question',
+                    instruction: 'What should change here?',
+                    x: 0.25,
+                    y: 0.4,
+                }
+            ],
+        });
+        return { task, session };
+    }
+    finally {
+        core.close();
+    }
+}
+function seedDocumentReviewFixture(projectRoot) {
+    const core = new TaskforceCore({
+        projectRoot,
+        storagePath: path.join(projectRoot, '.taskforce')
+    });
+    try {
+        const assetStore = core.getWorkspaceAssetStore();
+        const { basePath } = core.getPaths();
+        const storageKey = 'workspaces/workspace-1/assets/documents/asset-document-1-fixture-plan.md';
+        const absolutePath = path.join(basePath, storageKey);
+        fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+        fs.writeFileSync(absolutePath, '# Fixture plan\n\n## Rollout\n\nPlease tighten the rollout section.\n', 'utf8');
+        const asset = assetStore.upsertAsset({
+            assetId: 'asset-document-1',
+            workspaceId: 'workspace-1',
+            kind: 'document',
+            logicalName: 'Fixture plan',
+            originalFilename: 'fixture-plan.md',
+            mimeType: 'text/markdown',
+            storageProvider: 'local',
+            storageKey,
+            contentSha256: 'sha-document-1',
+            sizeBytes: 768,
+            documentId: 'doc-fixture-1',
+            referenceNumber: 123,
+            version: 2,
+            isLatest: true,
+        });
+        const session = core.createDocumentReviewSession({
+            workspaceId: 'workspace-1',
+            assetId: asset.assetId,
+            title: 'Fixture review',
+            actorId: 'owner-1',
+        });
+        const commented = core.addDocumentReviewComment({
+            workspaceId: 'workspace-1',
+            sessionId: session.id,
+            body: 'Please tighten the rollout section.',
+            anchor: { kind: 'line-range', startLine: 18, endLine: 24 },
+            actorId: 'owner-1',
+        });
+        return { asset, session: commented };
+    }
+    finally {
+        core.close();
+    }
+}
+describe('Taskforce MCP tool descriptions', () => {
+    it('keeps the runtime tool list aligned with the shared registry', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const result = await listTools(projectRoot, 'local');
+            const runtimeToolNames = result.tools.map((tool) => tool.name).sort();
+            const registryToolNames = Object.keys(MCP_TOOL_REGISTRY).sort();
+            expect(runtimeToolNames).toEqual(registryToolNames);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('keeps the cloud runtime tool list aligned with cloud-visible registry tools', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const result = await listTools(projectRoot, 'cloud');
+            const runtimeToolNames = result.tools.map((tool) => tool.name).sort();
+            const registryToolNames = Object.entries(MCP_TOOL_REGISTRY)
+                .filter(([, entry]) => entry.permission.kind !== 'local-only' && entry.permission.kind !== 'session-only')
+                .map(([name]) => name)
+                .sort();
+            expect(runtimeToolNames).toEqual(registryToolNames);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('includes local-only guidance in local runtime tool descriptions', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const result = await listTools(projectRoot, 'local');
+            const listTasks = getTool(result, 'list_tasks');
+            const getTask = getTool(result, 'get_task');
+            const getPaths = getTool(result, 'get_paths');
+            const searchImages = getTool(result, 'search_images');
+            const getDocument = getTool(result, 'get_document');
+            const searchDocuments = getTool(result, 'search_documents');
+            const listAnnotatedAttachmentSessions = getTool(result, 'get_annotated_attachment_sessions');
+            const readAnnotatedAttachmentPayload = getTool(result, 'read_annotated_attachment_payload');
+            const createAnnotatedAttachmentSession = getTool(result, 'create_annotated_attachment_session');
+            const deleteAnnotatedAttachmentSession = getTool(result, 'delete_annotated_attachment_session');
+            const reviewImage = getTool(result, 'review_image');
+            const addAnnotatedAttachmentMarker = getTool(result, 'add_annotated_attachment_marker');
+            const bulkAddAnnotatedAttachmentMarkers = getTool(result, 'bulk_add_annotated_attachment_markers');
+            const reorderAnnotatedAttachmentMarker = getTool(result, 'reorder_annotated_attachment_marker');
+            const getDocumentReviewSessions = getTool(result, 'get_document_review_sessions');
+            const addDocumentReviewComment = getTool(result, 'add_document_review_comment');
+            const updateDocumentReviewComment = getTool(result, 'update_document_review_comment');
+            expect(listTasks.description).toContain('Use format=json for programmatic use.');
+            expect(listTasks.description).toContain('NOTE: Use this tool instead of editing files directly to ensure data integrity.');
+            expect(getTask.description).toContain('Do not use this for image references like I-123 or document references like D-123.');
+            expect(getPaths.description).toContain('Get project and Taskforce storage paths.');
+            expect(searchImages.description).toContain('I-123 reference');
+            expect(getDocument.description).toContain('D-123');
+            expect(searchDocuments.description).toContain('D-123 reference');
+            expect(listAnnotatedAttachmentSessions.description).toContain('saved annotation sessions');
+            expect(readAnnotatedAttachmentPayload.description).toContain('derived crop hints');
+            expect(createAnnotatedAttachmentSession.description).toContain('before adding markers');
+            expect(deleteAnnotatedAttachmentSession.description).toContain('rather than deleting markers one by one');
+            expect(reviewImage.description).toContain('first-pass visual review');
+            expect(addAnnotatedAttachmentMarker.description).toContain('normalized 0..1 coordinates');
+            expect(bulkAddAnnotatedAttachmentMarkers.description).toContain('first-pass review');
+            expect(reorderAnnotatedAttachmentMarker.description).toContain('review order');
+            expect(getDocumentReviewSessions.description).toContain('D-123');
+            expect(addDocumentReviewComment.description).toContain('attached to the document rather than the task');
+            expect(updateDocumentReviewComment.description).toContain('without creating a new comment');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('omits local-file guidance in cloud runtime tool descriptions while keeping richer tool selection hints', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const result = await listTools(projectRoot, 'cloud');
+            const allDescriptions = result.tools.map((tool) => tool.description).join('\n');
+            const getConfig = getTool(result, 'get_config');
+            const searchTasks = getTool(result, 'search_tasks');
+            const getTask = getTool(result, 'get_task');
+            const searchImages = getTool(result, 'search_images');
+            const getImage = getTool(result, 'get_image');
+            const searchDocuments = getTool(result, 'search_documents');
+            const getDocument = getTool(result, 'get_document');
+            const readDocumentContent = getTool(result, 'read_document_content');
+            const getDocumentReviewSessions = getTool(result, 'get_document_review_sessions');
+            const getCurrentProfile = getTool(result, 'get_current_profile');
+            const createDocumentReviewSession = getTool(result, 'create_document_review_session');
+            const updateDocumentReviewSession = getTool(result, 'update_document_review_session');
+            const reviewDocument = getTool(result, 'review_document');
+            const addDocumentReviewComment = getTool(result, 'add_document_review_comment');
+            const getTaskAttachments = getTool(result, 'get_task_attachments');
+            const readTaskAttachment = getTool(result, 'read_task_attachment');
+            const deleteTaskAttachment = getTool(result, 'delete_task_attachment');
+            const deleteAnnotatedAttachmentSession = getTool(result, 'delete_annotated_attachment_session');
+            const archiveTask = getTool(result, 'archive_task');
+            const startTask = getTool(result, 'start_task');
+            const finishTask = getTool(result, 'finish_task');
+            const updateTask = getTool(result, 'update_task');
+            const assignTask = getTool(result, 'assign_task');
+            const bulkAssignTasks = getTool(result, 'bulk_assign_tasks');
+            const listAssignees = getTool(result, 'list_assignees');
+            const linkTaskContext = getTool(result, 'link_task_context');
+            const saveTaskAttachment = getTool(result, 'save_task_attachment');
+            const resolveProfile = getTool(result, 'resolve_profile');
+            expect(allDescriptions).not.toContain('NOTE: Use this tool instead of editing files directly to ensure data integrity.');
+            expect(getConfig.description).toContain('Call this at the start of a session or before create_task/update_task');
+            expect(searchTasks.description).toContain('Prefer this over list_tasks when looking for a specific task by name.');
+            expect(getTask.description).toContain('does not return attachment file contents');
+            expect(getTask.description).toContain('Do not fetch attachment path URLs directly');
+            expect(getTask.description).toContain('Do not use this for image references like I-123 or document references like D-123.');
+            expect(searchImages.description).toContain('get_image');
+            expect(getImage.description).toContain('Use this first when the user references an image');
+            expect(searchDocuments.description).toContain('get_document');
+            expect(searchDocuments.description).toContain('read_document_content');
+            expect(getDocument.description).toContain('Use this first when the user references a document');
+            expect(getDocument.description).toContain('read_document_content');
+            expect(getCurrentProfile.description).toContain('current profile id');
+            expect(getCurrentProfile.description).toContain('assigned to itself');
+            expect(readDocumentContent.description).toContain('inspect what it is reviewing');
+            expect(readDocumentContent.description).toContain('before adding review comments');
+            expect(getDocumentReviewSessions.description).toContain('read_document_content');
+            expect(createDocumentReviewSession.description).toContain('Requires AI identity via resolve_profile');
+            expect(updateDocumentReviewSession.description).toContain('Requires AI identity via resolve_profile');
+            expect(reviewDocument.description).toContain('lower-friction document review path');
+            expect(reviewDocument.description).toContain('Requires AI identity via resolve_profile');
+            expect(addDocumentReviewComment.description).toContain('Requires AI identity via resolve_profile');
+            expect(deleteAnnotatedAttachmentSession.description).toContain('whole session was created by mistake');
+            expect(getTaskAttachments.description).toContain('use read_task_attachment for file contents');
+            expect(getTaskAttachments.description).toContain('prefer get_document and read_document_content');
+            expect(readTaskAttachment.description).toContain('Prefer this tool over opening attachment path URLs directly');
+            expect(readTaskAttachment.description).toContain('canonical document');
+            expect(deleteTaskAttachment.description).toContain('Use get_task_attachments first');
+            expect(archiveTask.description).toContain('active tasks may still use status=done for final lookover');
+            expect(startTask.description).toContain('preferred AI start-of-task workflow');
+            expect(startTask.description).toContain('will not steal a task from a different assignee');
+            expect(finishTask.description).toContain("Use outcome='done' when work is complete");
+            expect(finishTask.description).toContain('default end-of-task handoff');
+            expect(finishTask.description).toContain('outcome=\'review\' when human validation or approval is needed');
+            expect(finishTask.description).toContain('either finish it with this tool or explain why it remains open');
+            expect(finishTask.description).toContain('This tool never archives automatically');
+            expect(updateTask.description).toContain('Use start_task when beginning active work on a tracked task');
+            expect(updateTask.description).toContain('prefer finish_task for the final completion or review handoff');
+            expect(assignTask.description).toContain('For assigning 3 or more tasks at once, use bulk_assign_tasks instead.');
+            expect(bulkAssignTasks.description).toContain('Preferred over repeated assign_task calls');
+            expect(listAssignees.description).toContain('List eligible assignees for the active workspace.');
+            expect(linkTaskContext.description).toContain('external http(s) URL');
+            expect(saveTaskAttachment.description).toContain('generated content');
+            expect(saveTaskAttachment.description).toContain('overwrite=true');
+            expect(resolveProfile.description).toContain('AI collaborator profile');
+            expect(resolveProfile.description).toContain('Update semantics');
+            expect(resolveProfile.description).toContain('empty strings are ignored rather than clearing');
+            expect(resolveProfile.inputSchema?.properties?.surfaceType).toBeDefined();
+            expect(resolveProfile.inputSchema?.properties?.surfaceType?.description).toContain('self-declared AI surface type');
+            expect(resolveProfile.inputSchema?.properties?.surfaceType?.description).toContain('agent for a persistent named AI collaborator in Taskforce');
+            expect(resolveProfile.inputSchema?.properties?.surfaceType?.description).toContain('coding_tool for the coding surface or terminal tool itself');
+            expect(resolveProfile.inputSchema?.properties?.surfaceType?.description).toContain('If you are unsure and you are registering a named collaborator');
+            const surfaceTypeSchema = resolveProfile.inputSchema?.properties?.surfaceType;
+            expect(surfaceTypeSchema?.anyOf?.[0]?.enum).toEqual([
+                'chat_app',
+                'ide',
+                'coding_tool',
+                'agent',
+                'other'
+            ]);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('creates and re-resolves ai profiles through resolve_profile', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const first = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
+                name: 'Codex',
+                icon: 'Bot',
+                color: '#ef6c00',
+                description: 'Builds features and fixes regressions',
+                role: 'Implementer',
+                provider: 'OpenAI',
+                model: 'gpt-5.4',
+                surfaceType: 'coding_tool'
+            }));
+            expect(first.created).toBe(true);
+            expect(first.profileToken).toMatch(/^tfp_/);
+            expect(first.profile.id).toMatch(/^ai-profile-/);
+            expect(first.profile.profileToken).toMatch(/^tfp_/);
+            expect(first.profileToken).toBe(first.profile.profileToken);
+            expect(first.profile.description).toBe('Builds features and fixes regressions');
+            expect(first.profile.role).toBe('Implementer');
+            expect(first.profile.provider).toBe('OpenAI');
+            expect(first.profile.model).toBe('gpt-5.4');
+            expect(first.profile.surfaceType).toBe('coding_tool');
+            const second = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
+                name: 'Ignored Rename',
+                description: '',
+                surfaceType: null,
+                profileToken: first.profile.profileToken
+            }));
+            expect(second.created).toBe(false);
+            expect(second.profileToken).toBe(first.profile.profileToken);
+            expect(second.profile.id).toBe(first.profile.id);
+            expect(second.profile.name).toBe('Ignored Rename');
+            expect(second.profile.description).toBe('Builds features and fixes regressions');
+            expect(second.profile.surfaceType).toBeNull();
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('updates profile metadata when resolve_profile reuses an existing exact-match profile without a token', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const first = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
+                name: 'John Drake',
+                icon: 'Bot',
+                color: '#64748b'
+            }));
+            expect(first.created).toBe(true);
+            expect(first.profile.description).toBeNull();
+            expect(first.profile.role).toBeNull();
+            expect(first.profile.provider).toBeNull();
+            expect(first.profile.model).toBeNull();
+            const second = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
+                name: 'John Drake',
+                icon: '🕴️',
+                color: '#2F3A4A',
+                description: 'AI collaborator for Taskforce',
+                role: 'Advisor',
+                provider: 'OpenClaw',
+                model: 'gpt-5.4',
+                surfaceType: 'agent'
+            }));
+            expect(second.created).toBe(false);
+            expect(second.profile.id).toBe(first.profile.id);
+            expect(second.profile.icon).toBe('🕴️');
+            expect(second.profile.color).toBe('#2F3A4A');
+            expect(second.profile.description).toBe('AI collaborator for Taskforce');
+            expect(second.profile.role).toBe('Advisor');
+            expect(second.profile.provider).toBe('OpenClaw');
+            expect(second.profile.model).toBe('gpt-5.4');
+            expect(second.profile.surfaceType).toBe('agent');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('allows read-only MCP tools before resolve_profile', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const seeded = core.createTask({ title: 'Readable before profile' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const config = parseToolJson(await callTool(projectRoot, 'local', 'get_config', {}));
+            const task = parseToolJson(await callTool(projectRoot, 'local', 'get_task', { id: seeded.referenceLabel }));
+            expect(Array.isArray(config.categories)).toBe(true);
+            expect(task.id).toBe(seeded.id);
+            expect(task.title).toBe('Readable before profile');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('uses the active workspace taxonomy for get_config and create_task', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            core.createWorkspace({ workspaceId: 'workspace-2', name: 'Workspace 2' });
+            core.ensureBootstrapUserAccess({
+                userId: 'owner-1',
+                workspaceId: 'workspace-2',
+                role: 'owner',
+                email: 'owner-1@example.com'
+            });
+            core.updateCategories([{ value: 'default', label: 'Default' }], 'workspace-2');
+            core.updateTypes([
+                { value: 'feature', label: 'Feature' },
+                { value: 'bug', label: 'Bug' },
+                { value: 'chore', label: 'Chore' }
+            ], 'workspace-2');
+            core.updatePriorities([
+                { value: 1, label: 'Low' },
+                { value: 2, label: 'Medium' },
+                { value: 3, label: 'High' },
+                { value: 4, label: 'Critical' }
+            ], 'workspace-2');
+            core.close();
+            const config = parseToolJson(await callTool(projectRoot, 'cloud', 'get_config', {}, {
+                workspaceId: 'workspace-2'
+            }));
+            expect(config.types.map((type) => type.value)).toEqual(['feature', 'bug', 'chore']);
+            expect(config.priorities.map((priority) => priority.value)).toEqual([1, 2, 3, 4]);
+            const created = parseToolJson(await callTool(projectRoot, 'cloud', 'create_task', {
+                title: 'Workspace scoped task',
+                type: 'feature',
+                priority: 4
+            }, {
+                workspaceId: 'workspace-2'
+            }));
+            expect(created.type).toBe('feature');
+            expect(created.priority).toBe(4);
+            const createdWithDefaultType = parseToolJson(await callTool(projectRoot, 'cloud', 'create_task', {
+                title: 'Workspace scoped default type'
+            }, {
+                workspaceId: 'workspace-2'
+            }));
+            expect(createdWithDefaultType.type).toBe('feature');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('returns structured taxonomy confirmation details for recoverable MCP errors', async () => {
+        const { buildRecoverableToolErrorResult } = await import('./runtime');
+        const result = buildRecoverableToolErrorResult(new TaskforceRuleError('Task contains unresolved taxonomy values. Confirmation is required before create.', 409, 'TAXONOMY_NEEDS_CONFIRMATION', {
+            needs_confirmation: true,
+            unresolved: [{ field: 'type', submitted: 'deliverable', suggestions: [{ value: 'feature', label: 'Feature', confidence: 0.9 }] }],
+            normalized_retry_payload: { title: 'Needs taxonomy confirmation', type: 'feature', category: 'default' }
+        }));
+        const payload = parseToolJson(result);
+        expect(payload.success).toBe(false);
+        expect(payload.code).toBe('TAXONOMY_NEEDS_CONFIRMATION');
+        expect(payload.needs_confirmation).toBe(true);
+        expect(payload.details).toEqual(expect.objectContaining({
+            needs_confirmation: true,
+            unresolved: expect.arrayContaining([
+                expect.objectContaining({
+                    field: 'type',
+                    submitted: 'deliverable'
+                })
+            ]),
+            normalized_retry_payload: expect.objectContaining({
+                title: 'Needs taxonomy confirmation',
+                type: 'feature',
+                category: 'default'
+            })
+        }));
+    });
+    it('blocks mutating MCP tools until resolve_profile is called', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const localResult = await callTool(projectRoot, 'local', 'create_task', {
+                title: 'Should not be created'
+            }, { resolveProfile: false });
+            expect(localResult.isError).toBe(true);
+            expect(localResult.content?.[0]?.text).toContain('Call resolve_profile first');
+            expect(localResult.content?.[0]?.text).toContain('pass profileToken on mutating calls');
+            const localPayload = parseToolJson(localResult);
+            expect(localPayload.code).toBe('AI_PROFILE_REQUIRED');
+            expect(localPayload.nextTool).toBe('resolve_profile');
+            expect(localPayload.retryHint).toContain('profileToken');
+            const cloudResult = await callTool(projectRoot, 'cloud', 'create_task', {
+                title: 'Should not be created in cloud either'
+            }, { resolveProfile: false });
+            expect(cloudResult.isError).toBe(true);
+            expect(cloudResult.content?.[0]?.text).toContain('Call resolve_profile first');
+            const after = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const tasks = after.listTasks('workspace-1').tasks;
+                expect(tasks.some((task) => task.title === 'Should not be created')).toBe(false);
+                expect(tasks.some((task) => task.title === 'Should not be created in cloud either')).toBe(false);
+            }
+            finally {
+                after.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('auto-binds a configured cloud AI name for mutating tools', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const created = parseToolJson(await callTool(projectRoot, 'cloud', 'create_task', {
+                title: 'Automation bootstrap task'
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileName: 'Automation Codex'
+            }));
+            expect(created.title).toBe('Automation bootstrap task');
+            expect(created.createdBy).toMatch(/^ai-profile-/);
+            expect(created.createdByActor).toEqual(expect.objectContaining({
+                label: 'Automation Codex',
+                kind: 'ai'
+            }));
+            expect(created.assignee).toBe('unassigned');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('persists configured cloud AI metadata during auto-bind bootstrap', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            await callTool(projectRoot, 'cloud', 'create_task', {
+                title: 'Metadata bootstrap task'
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileName: 'Automation Codex',
+                authAiProfileDescription: 'OpenAI Codex coding agent connected through MCP.',
+                authAiProfileRole: 'Coding Agent',
+                authAiProfileProvider: 'OpenAI',
+                authAiProfileModel: 'Codex',
+                authAiProfileSurfaceType: 'coding_tool'
+            });
+            const currentProfile = parseToolJson(await callTool(projectRoot, 'cloud', 'get_current_profile', {}, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileName: 'Automation Codex',
+                authAiProfileDescription: 'OpenAI Codex coding agent connected through MCP.',
+                authAiProfileRole: 'Coding Agent',
+                authAiProfileProvider: 'OpenAI',
+                authAiProfileModel: 'Codex',
+                authAiProfileSurfaceType: 'coding_tool'
+            }));
+            expect(currentProfile.profile).toEqual(expect.objectContaining({
+                name: 'Automation Codex',
+                description: 'OpenAI Codex coding agent connected through MCP.',
+                role: 'Coding Agent',
+                provider: 'OpenAI',
+                model: 'Codex',
+                surfaceType: 'coding_tool'
+            }));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('allows mutating MCP tools in a fresh runtime when profileToken is passed', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const resolved = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
+                name: 'Codex',
+                icon: 'Bot',
+                color: '#ef6c00'
+            }, { resolveProfile: false }));
+            const created = parseToolJson(await callTool(projectRoot, 'local', 'create_task', {
+                title: 'Stateless profile token write',
+                profileToken: resolved.profile.profileToken,
+            }, { resolveProfile: false }));
+            expect(created.title).toBe('Stateless profile token write');
+            expect(created.createdBy).toBe(resolved.profile.id);
+            expect(created.createdByActor).toEqual(expect.objectContaining({
+                id: resolved.profile.id,
+                username: resolved.profile.username
+            }));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('allows mutating cloud MCP tools when the connection is configured with an AI profile token', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const resolved = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
+                name: 'Automation Codex'
+            }, { resolveProfile: false }));
+            const created = parseToolJson(await callTool(projectRoot, 'cloud', 'create_task', {
+                title: 'Configured token write'
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileToken: resolved.profile.profileToken
+            }));
+            expect(created.createdBy).toBe(resolved.profile.id);
+            expect(created.createdByActor).toEqual(expect.objectContaining({
+                id: resolved.profile.id,
+                username: resolved.profile.username
+            }));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('recovers from a stale configured cloud AI profile token when a valid AI name is provided', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const created = parseToolJson(await callTool(projectRoot, 'cloud', 'create_task', {
+                title: 'Recovered automation write'
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileToken: 'tfp_stale_automation_token',
+                authAiProfileName: 'Automation Codex'
+            }));
+            expect(created.title).toBe('Recovered automation write');
+            expect(created.createdBy).toMatch(/^ai-profile-/);
+            expect(created.createdByActor).toEqual(expect.objectContaining({
+                label: 'Automation Codex',
+                kind: 'ai'
+            }));
+            const currentProfile = parseToolJson(await callTool(projectRoot, 'cloud', 'get_current_profile', {}, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileToken: 'tfp_stale_automation_token',
+                authAiProfileName: 'Automation Codex'
+            }));
+            expect(currentProfile.identityBound).toBe(true);
+            expect(currentProfile.profileToken).toMatch(/^tfp_/);
+            expect(currentProfile.profile).toEqual(expect.objectContaining({
+                name: 'Automation Codex',
+                profileToken: expect.stringMatching(/^tfp_/)
+            }));
+            expect(currentProfile.profileToken).toBe(currentProfile.profile.profileToken);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('rejects invalid profileToken values on mutating MCP tools', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const result = await callTool(projectRoot, 'local', 'create_task', {
+                title: 'Invalid token write',
+                profileToken: 'tfp_invalid_token',
+            }, { resolveProfile: false });
+            expect(result.isError).toBe(true);
+            expect(result.content?.[0]?.text).toContain('Invalid AI profile token');
+            const payload = parseToolJson(result);
+            expect(payload.code).toBe('INVALID_AI_PROFILE_TOKEN');
+            expect(payload.nextTool).toBe('resolve_profile');
+            expect(payload.retryHint).toContain('fresh profileToken');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('recovers from an invalid per-call profileToken when the connection has a valid AI name', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const created = parseToolJson(await callTool(projectRoot, 'cloud', 'create_task', {
+                title: 'Recovered per-call token write',
+                profileToken: 'tfp_invalid_token',
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileName: 'Automation Codex'
+            }));
+            expect(created.title).toBe('Recovered per-call token write');
+            expect(created.createdByActor).toEqual(expect.objectContaining({
+                label: 'Automation Codex',
+                kind: 'ai'
+            }));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('claims unassigned tasks and marks them in progress through start_task', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const seeded = core.createTask({
+                title: 'Start helper unassigned path',
+                status: 'task',
+                assignee: 'unassigned'
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            core.close();
+            const result = parseToolJson(await callTool(projectRoot, 'local', 'start_task', {
+                id: seeded.referenceLabel
+            }));
+            expect(result.started).toBe(true);
+            expect(result.claimed).toBe(true);
+            expect(result.statusChanged).toBe(true);
+            expect(result.previousAssignee).toBe('unassigned');
+            expect(result.previousStatus).toBe('task');
+            expect(result.task.status).toBe('in-progress');
+            expect(result.task.assignee).toMatch(/^ai-profile-/);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('sets tasks already assigned to the current AI in progress without stealing ownership', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const profile = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
+                name: 'Codex',
+                icon: 'Bot',
+                color: '#ef6c00'
+            }));
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const seeded = core.createTask({
+                title: 'Start helper owned path',
+                status: 'task',
+                assignee: profile.profile.id
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            core.close();
+            const result = parseToolJson(await callTool(projectRoot, 'local', 'start_task', {
+                id: seeded.referenceLabel
+            }));
+            expect(result.started).toBe(true);
+            expect(result.claimed).toBe(false);
+            expect(result.statusChanged).toBe(true);
+            expect(result.previousAssignee).toBe(profile.profile.id);
+            expect(result.task.assignee).toBe(profile.profile.id);
+            expect(result.task.status).toBe('in-progress');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('refuses to steal tasks already assigned to someone else through start_task', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const seeded = core.createTask({
+                title: 'Start helper assignee refusal',
+                status: 'task',
+                assignee: 'owner-1'
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            core.close();
+            const result = await callTool(projectRoot, 'local', 'start_task', {
+                id: seeded.referenceLabel
+            });
+            expect(result.isError).toBe(true);
+            expect(result.content?.[0]?.text).toContain('will not steal work from another assignee');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('rejects terminal tasks through start_task', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const seeded = core.createTask({
+                title: 'Start helper terminal refusal',
+                status: 'done',
+                assignee: 'unassigned'
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            core.close();
+            const result = await callTool(projectRoot, 'local', 'start_task', {
+                id: seeded.referenceLabel
+            });
+            expect(result.isError).toBe(true);
+            expect(result.content?.[0]?.text).toContain('must be reopened explicitly');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('requires AI identity for start_task when bootstrap is disabled', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const seeded = core.createTask({
+                title: 'Start helper identity guard',
+                status: 'task',
+                assignee: 'unassigned'
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            core.close();
+            const result = await callTool(projectRoot, 'local', 'start_task', {
+                id: seeded.referenceLabel
+            }, { resolveProfile: false });
+            expect(result.isError).toBe(true);
+            const payload = parseToolJson(result);
+            expect(payload.code).toBe('AI_PROFILE_REQUIRED');
+            expect(payload.nextTool).toBe('resolve_profile');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('marks completed tasks done without archiving them through finish_task', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const seeded = core.createTask({
+                title: 'Finish helper done path',
+                status: 'in-progress'
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            core.close();
+            const result = parseToolJson(await callTool(projectRoot, 'local', 'finish_task', {
+                id: seeded.referenceLabel,
+                outcome: 'done',
+                summary: 'Implementation completed'
+            }));
+            expect(result.task.status).toBe('done');
+            expect(result.completion).toEqual(expect.objectContaining({
+                outcome: 'done',
+                archived: false,
+                summary: 'Implementation completed'
+            }));
+            const after = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                expect(after.listTasks('workspace-1').tasks.some((task) => task.id === seeded.id && task.status === 'done')).toBe(true);
+                expect(after.listArchive('workspace-1').archived.some((task) => task.id === seeded.id)).toBe(false);
+            }
+            finally {
+                after.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('hands review tasks to the current human user through finish_task', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            core.ensureBootstrapUserAccess({
+                userId: 'reviewer-1',
+                workspaceId: 'workspace-1',
+                role: 'member',
+                email: 'reviewer-1@example.com'
+            });
+            const seeded = core.createTask({
+                title: 'Finish helper review path',
+                status: 'in-progress',
+                assignee: 'unassigned'
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            core.close();
+            const result = parseToolJson(await callTool(projectRoot, 'cloud', 'finish_task', {
+                id: seeded.referenceLabel,
+                outcome: 'review'
+            }, { authUserId: 'reviewer-1' }));
+            expect(result.task.status).toBe('review');
+            expect(result.task.assignee).toBe('reviewer-1');
+            expect(result.completion).toEqual(expect.objectContaining({
+                outcome: 'review',
+                archived: false,
+                reviewerResolution: expect.objectContaining({
+                    assignee: 'reviewer-1',
+                    source: 'current_user'
+                })
+            }));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('preserves an existing human owner when handing off a task for review', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            core.ensureBootstrapUserAccess({
+                userId: 'reviewer-2',
+                workspaceId: 'workspace-1',
+                role: 'member',
+                email: 'reviewer-2@example.com'
+            });
+            const seeded = core.createTask({
+                title: 'Preserve existing human owner',
+                status: 'in-progress',
+                assignee: 'reviewer-2'
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            core.close();
+            const result = parseToolJson(await callTool(projectRoot, 'cloud', 'finish_task', {
+                id: seeded.referenceLabel,
+                outcome: 'review'
+            }, { authUserId: 'owner-1' }));
+            expect(result.task.status).toBe('review');
+            expect(result.task.assignee).toBe('reviewer-2');
+            expect(result.completion.reviewerResolution).toEqual(expect.objectContaining({
+                assignee: 'reviewer-2',
+                source: 'existing_human_owner'
+            }));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('lists eligible assignee ids in MCP tool schemas instead of generic agent guidance', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            core.ensureBootstrapUserAccess({
+                userId: 'member-2',
+                workspaceId: 'workspace-1',
+                role: 'member',
+                email: 'member-2@example.com'
+            });
+            core.resolveAiProfile({
+                workspaceId: 'workspace-1',
+                name: 'Codex',
+                icon: 'Bot',
+                color: '#ef6c00'
+            });
+            core.close();
+            const result = await listTools(projectRoot, 'local');
+            const assignTask = getTool(result, 'assign_task');
+            const createTask = getTool(result, 'create_task');
+            expect(assignTask.inputSchema?.properties?.assignee?.description).toContain('member-2');
+            expect(assignTask.inputSchema?.properties?.assignee?.description).toContain('Codex');
+            expect(assignTask.inputSchema?.properties?.assignee?.description).not.toContain("Use 'agent'");
+            expect(createTask.inputSchema?.properties?.profileToken?.description).toContain('does not preserve session identity');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('returns eligible assignees and marks the current resolved AI profile', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            core.ensureBootstrapUserAccess({
+                userId: 'member-2',
+                workspaceId: 'workspace-1',
+                role: 'member',
+                email: 'member-2@example.com'
+            });
+            core.close();
+            const runtime = createTaskforceMcpServer({
+                projectRoot,
+                runtimeMode: 'local',
+                logStartup: false
+            });
+            const handler = runtime.server._requestHandlers.get('tools/call');
+            if (!handler)
+                throw new Error('tools/call handler not registered');
+            const resolved = parseToolJson(await handler({
+                jsonrpc: '2.0',
+                id: 'test-tools-call-resolve-profile',
+                method: 'tools/call',
+                params: {
+                    name: 'resolve_profile',
+                    arguments: {
+                        name: 'Codex',
+                        icon: 'Bot',
+                        color: '#ef6c00',
+                        description: 'Builds and repairs product code',
+                        role: 'Implementer',
+                        provider: 'OpenAI',
+                        model: 'gpt-5.4'
+                    }
+                }
+            }, {}));
+            const payload = parseToolJson(await handler({
+                jsonrpc: '2.0',
+                id: 'test-tools-call-list-assignees',
+                method: 'tools/call',
+                params: {
+                    name: 'list_assignees',
+                    arguments: {}
+                }
+            }, {}));
+            expect(payload.workspaceId).toBe('workspace-1');
+            expect(payload.assignees).toEqual(expect.arrayContaining([
+                expect.objectContaining({ id: 'owner-1', kind: 'member', username: 'owner-1@example.com' }),
+                expect.objectContaining({ id: 'member-2', kind: 'member', username: 'member-2@example.com' }),
+                expect.objectContaining({
+                    id: resolved.profile.id,
+                    kind: 'agent',
+                    username: resolved.profile.username,
+                    description: 'Builds and repairs product code',
+                    role: 'Implementer',
+                    provider: 'OpenAI',
+                    model: 'gpt-5.4',
+                    isCurrentProfile: true
+                })
+            ]));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('returns the current AI profile and suggested assignee filter', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const runtime = createTaskforceMcpServer({
+                projectRoot,
+                runtimeMode: 'local',
+                logStartup: false
+            });
+            const handler = runtime.server._requestHandlers.get('tools/call');
+            if (!handler)
+                throw new Error('tools/call handler not registered');
+            const resolved = parseToolJson(await handler({
+                jsonrpc: '2.0',
+                id: 'test-tools-call-resolve-profile-current',
+                method: 'tools/call',
+                params: {
+                    name: 'resolve_profile',
+                    arguments: {
+                        name: 'Codex',
+                        icon: 'Bot',
+                        color: '#ef6c00'
+                    }
+                }
+            }, {}));
+            const payload = parseToolJson(await handler({
+                jsonrpc: '2.0',
+                id: 'test-tools-call-get-current-profile',
+                method: 'tools/call',
+                params: {
+                    name: 'get_current_profile',
+                    arguments: {}
+                }
+            }, {}));
+            expect(payload.identityBound).toBe(true);
+            expect(payload.profile).toEqual(expect.objectContaining({
+                id: resolved.profile.id,
+                username: resolved.profile.username,
+                profileToken: resolved.profile.profileToken,
+            }));
+            expect(payload.taskFilter).toEqual({ assignee: resolved.profile.id });
+            expect(payload.nextTool).toBe('list_tasks');
+            expect(payload.suggestedArgs).toEqual({ assignee: resolved.profile.id, format: 'json' });
+            expect(payload.guidance).toContain('suggestedArgs');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('guides agents to resolve_profile when no current AI profile is bound', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const payload = parseToolJson(await callTool(projectRoot, 'local', 'get_current_profile', {}, {
+                resolveProfile: false
+            }));
+            expect(payload.identityBound).toBe(false);
+            expect(payload.profile).toBeNull();
+            expect(payload.taskFilter).toBeNull();
+            expect(payload.nextTool).toBe('resolve_profile');
+            expect(payload.suggestedArgs).toEqual({ name: 'Your AI name' });
+            expect(payload.guidance).toContain('Call resolve_profile first');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('auto-binds get_current_profile from a configured cloud AI name', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const payload = parseToolJson(await callTool(projectRoot, 'cloud', 'get_current_profile', {}, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileName: 'Automation Codex'
+            }));
+            expect(payload.identityBound).toBe(true);
+            expect(payload.profile).toEqual(expect.objectContaining({
+                name: 'Automation Codex',
+                username: 'automation-codex',
+                profileToken: expect.stringMatching(/^tfp_/)
+            }));
+            expect(payload.taskFilter).toEqual({ assignee: payload.profile.id });
+            expect(payload.nextTool).toBe('list_tasks');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('searches tasks by T-XXX reference label via reference_number', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            core.createTask({
+                id: 'task-ref-587',
+                referenceNumber: 587,
+                title: 'Reference search target'
+            }, {
+                workspaceId: 'workspace-1',
+                allowClientProvidedId: true
+            });
+            core.close();
+            const result = await callTool(projectRoot, 'cloud', 'search_tasks', { query: 'T-587' }, {
+                workspaceId: 'workspace-1',
+                authUserId: 'owner-1'
+            });
+            expect(result.content?.[0]?.text).toContain('T-587');
+            expect(result.content?.[0]?.text).toContain('Reference search target');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('keeps T-XXX lookup errors scoped to the active workspace', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            core.createWorkspace({ workspaceId: 'workspace-2', name: 'Workspace 2' });
+            core.ensureBootstrapUserAccess({
+                userId: 'owner-1',
+                workspaceId: 'workspace-2',
+                role: 'owner',
+                email: 'owner-1@example.com'
+            });
+            core.createTask({
+                title: 'Other workspace task'
+            }, {
+                workspaceId: 'workspace-2'
+            });
+            core.close();
+            const result = await callTool(projectRoot, 'cloud', 'get_task', { id: 'T-1' }, {
+                workspaceId: 'workspace-1',
+                authUserId: 'owner-1'
+            });
+            expect(result.content?.[0]?.text).toContain('Task T-1 not found in workspace workspace-1.');
+            expect(result.content?.[0]?.text).not.toContain('workspace-2');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('lists and reads initiative and workstream resources by readable reference', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const initiative = core.createInitiative({
+                title: 'Planning initiative'
+            }, 'workspace-1');
+            const workstream = core.createWorkstream({
+                title: 'Planning workstream',
+                initiativeId: initiative.id
+            }, 'workspace-1');
+            core.createTask({
+                title: 'Linked planning task',
+                workstreamId: workstream.id
+            }, {
+                workspaceId: 'workspace-1'
+            });
+            const archivedTask = core.createTask({
+                title: 'Archived planning task',
+                workstreamId: workstream.id
+            }, {
+                workspaceId: 'workspace-1'
+            });
+            core.archiveTask(archivedTask.id, false, undefined, 'workspace-1');
+            core.close();
+            const listed = await listResources(projectRoot, 'cloud', {
+                workspaceId: 'workspace-1',
+                authUserId: 'owner-1'
+            });
+            expect(listed.resources.map((resource) => resource.uri)).toEqual(expect.arrayContaining([
+                `taskforce://${path.basename(projectRoot)}/initiatives`,
+                `taskforce://${path.basename(projectRoot)}/workstreams`,
+            ]));
+            const initiativeResource = await readResource(projectRoot, 'cloud', `taskforce://${path.basename(projectRoot)}/initiatives/${initiative.referenceLabel}`, {
+                workspaceId: 'workspace-1',
+                authUserId: 'owner-1'
+            });
+            const initiativePayload = JSON.parse(String(initiativeResource.contents[0]?.text || '{}'));
+            expect(initiativePayload.initiative.referenceLabel).toBe(initiative.referenceLabel);
+            expect(initiativePayload.taskCount).toBe(2);
+            expect(initiativePayload.workstreams).toEqual(expect.arrayContaining([
+                expect.objectContaining({ id: workstream.id, referenceLabel: workstream.referenceLabel })
+            ]));
+            const workstreamResource = await readResource(projectRoot, 'cloud', `taskforce://${path.basename(projectRoot)}/workstreams/${workstream.referenceLabel}`, {
+                workspaceId: 'workspace-1',
+                authUserId: 'owner-1'
+            });
+            const workstreamPayload = JSON.parse(String(workstreamResource.contents[0]?.text || '{}'));
+            expect(workstreamPayload.workstream.referenceLabel).toBe(workstream.referenceLabel);
+            expect(workstreamPayload.taskCount).toBe(2);
+            expect(workstreamPayload.tasks).toEqual(expect.arrayContaining([
+                expect.objectContaining({ title: 'Linked planning task', workstreamId: workstream.id }),
+                expect.objectContaining({ title: 'Archived planning task', workstreamId: workstream.id, isArchived: true, status: 'done' })
+            ]));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('manages planning entities, relationships, and structured checklist tools', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const createdInitiative = parseToolJson(await callTool(projectRoot, 'local', 'create_initiative', {
+                title: 'Launch initiative'
+            }));
+            expect(createdInitiative.initiative.referenceLabel).toMatch(/^IN-/);
+            const createdWorkstream = parseToolJson(await callTool(projectRoot, 'local', 'create_workstream', {
+                title: 'Launch workstream',
+                initiativeId: createdInitiative.initiative.referenceLabel
+            }));
+            expect(createdWorkstream.workstream.referenceLabel).toMatch(/^WS-/);
+            expect(createdWorkstream.workstream.initiativeId).toBe(createdInitiative.initiative.id);
+            const createdTask = parseToolJson(await callTool(projectRoot, 'local', 'create_task', {
+                title: 'Task for MCP planning'
+            }));
+            const taskLinked = parseToolJson(await callTool(projectRoot, 'local', 'set_task_workstream', {
+                taskId: createdTask.referenceLabel,
+                workstreamId: createdWorkstream.workstream.referenceLabel
+            }));
+            expect(taskLinked.workstreamId).toBe(createdWorkstream.workstream.id);
+            const checklistReplaced = parseToolJson(await callTool(projectRoot, 'local', 'replace_task_checklist', {
+                taskId: createdTask.referenceLabel,
+                items: [
+                    { title: 'First checklist item', isCompleted: false },
+                    { title: 'Second checklist item', isCompleted: true }
+                ]
+            }));
+            expect(checklistReplaced.items).toHaveLength(2);
+            const checklistRead = parseToolJson(await callTool(projectRoot, 'local', 'get_task_checklist', {
+                taskId: createdTask.referenceLabel
+            }));
+            expect(checklistRead.items.map((item) => item.title)).toEqual(['First checklist item', 'Second checklist item']);
+            const workstreamCleared = parseToolJson(await callTool(projectRoot, 'local', 'clear_workstream_initiative', {
+                workstreamId: createdWorkstream.workstream.referenceLabel
+            }));
+            expect(workstreamCleared.workstream.initiativeId).toBeNull();
+            const workstreamReset = parseToolJson(await callTool(projectRoot, 'local', 'set_workstream_initiative', {
+                workstreamId: createdWorkstream.workstream.referenceLabel,
+                initiativeId: createdInitiative.initiative.referenceLabel
+            }));
+            expect(workstreamReset.workstream.initiativeId).toBe(createdInitiative.initiative.id);
+            const archivedWorkstream = parseToolJson(await callTool(projectRoot, 'local', 'archive_workstream', {
+                id: createdWorkstream.workstream.referenceLabel
+            }));
+            expect(archivedWorkstream.workstream.isArchived).toBe(true);
+            const unarchivedWorkstream = parseToolJson(await callTool(projectRoot, 'local', 'unarchive_workstream', {
+                id: createdWorkstream.workstream.referenceLabel
+            }));
+            expect(unarchivedWorkstream.workstream.isArchived).toBe(false);
+            const archivedInitiative = parseToolJson(await callTool(projectRoot, 'local', 'archive_initiative', {
+                id: createdInitiative.initiative.referenceLabel
+            }));
+            expect(archivedInitiative.initiative.isArchived).toBe(true);
+            const unarchivedInitiative = parseToolJson(await callTool(projectRoot, 'local', 'unarchive_initiative', {
+                id: createdInitiative.initiative.referenceLabel
+            }));
+            expect(unarchivedInitiative.initiative.isArchived).toBe(false);
+            const taskCleared = parseToolJson(await callTool(projectRoot, 'local', 'clear_task_workstream', {
+                taskId: createdTask.referenceLabel
+            }));
+            expect(taskCleared.workstreamId).toBeNull();
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('creates MCP tasks as unassigned when no explicit assignee is provided', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const created = parseToolJson(await callTool(projectRoot, 'local', 'create_task', {
+                title: 'Unassigned by default'
+            }));
+            expect(created.assignee).toBe('unassigned');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('reads task resources by T-XXX reference and exposes version/scope in config resource', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Resource reference task' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const taskResource = await readResource(projectRoot, 'cloud', `taskforce://${path.basename(projectRoot)}/tasks/${task.referenceLabel}`, {
+                workspaceId: 'workspace-1',
+                authUserId: 'owner-1'
+            });
+            const configResource = await readResource(projectRoot, 'cloud', `taskforce://${path.basename(projectRoot)}/config`, {
+                workspaceId: 'workspace-1',
+                authUserId: 'owner-1'
+            });
+            const taskPayload = JSON.parse(String(taskResource.contents[0]?.text || '{}'));
+            const configPayload = JSON.parse(String(configResource.contents[0]?.text || '{}'));
+            expect(taskPayload.id).toBe(task.id);
+            expect(taskPayload.referenceLabel).toBe(task.referenceLabel);
+            expect(configPayload.server?.version).toBeTruthy();
+            expect(configPayload.server?.runtimeMode).toBe('cloud');
+            expect(configPayload.scope?.workspaceId).toBe('workspace-1');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('persists save_task_attachment through canonical task attachments', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({
+                title: 'Attachment test'
+            }, {
+                workspaceId: 'workspace-1'
+            });
+            core.close();
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.id,
+                filename: 'smoke-test.txt',
+                content: 'hello from runtime test'
+            });
+            const after = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const updated = after.getTask(task.id, 'workspace-1');
+                expect(updated?.attachments).toHaveLength(1);
+                const first = updated?.attachments?.[0];
+                expect(typeof first).toBe('object');
+                expect(first.fsPath).toContain('workspaces/workspace-1/assets/files/');
+            }
+            finally {
+                after.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('allows save_task_attachment in cloud runtime with inline content', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Cloud attachment test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.id,
+                filename: 'cloud-note.md',
+                content: '# Cloud Note'
+            });
+            const after = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const updated = after.getTask(task.id, 'workspace-1');
+                expect(updated?.attachments).toHaveLength(1);
+                expect(updated?.attachments?.[0]).toMatchObject({
+                    path: expect.stringMatching(/^\/api\/taskforce\/documents\/.+\/content$/),
+                    caption: 'cloud-note.md',
+                    displayName: 'cloud-note.md',
+                    originalFilename: 'cloud-note.md'
+                });
+                expect((updated?.attachments?.[0]).fsPath).toContain('workspaces/workspace-1/assets/documents/');
+            }
+            finally {
+                after.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('allows generic markdown review attachments without requiring the legacy review template', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Generic review attachment test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.id,
+                filename: 'review.md',
+                content: ['## Review Verdict', '### Findings', '- Looks good overall.'].join('\n')
+            });
+            const after = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const updated = after.getTask(task.id, 'workspace-1');
+                expect(updated?.attachments).toHaveLength(1);
+                expect(updated?.attachments?.[0]).toMatchObject({
+                    originalFilename: 'review.md',
+                    caption: 'review.md',
+                    displayName: 'review.md'
+                });
+            }
+            finally {
+                after.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('uses the caption as the canonical logical name for markdown attachments', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Canonical markdown naming test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.id,
+                filename: 'v2.md',
+                content: '# Plan\n',
+                caption: 'AI Profiles - Implementation Plan v2'
+            });
+            const after = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const updated = after.getTask(task.id, 'workspace-1');
+                expect(updated?.attachments?.[0]).toMatchObject({
+                    caption: 'AI Profiles - Implementation Plan v2',
+                    displayName: 'AI Profiles - Implementation Plan v2',
+                    originalFilename: 'v2.md'
+                });
+                const attachmentAssetId = updated?.attachments?.[0]?.assetId;
+                const store = new WorkspaceAssetStore(after.getDatabaseAdapter(), after.getTenantId());
+                const asset = store.get(String(attachmentAssetId || ''), 'workspace-1');
+                expect(asset).toEqual(expect.objectContaining({
+                    logicalName: 'AI Profiles - Implementation Plan v2',
+                    originalFilename: 'v2.md'
+                }));
+                expect(store.listLinksForAsset(String(attachmentAssetId || ''), 'workspace-1')).toEqual([
+                    expect.objectContaining({
+                        taskId: task.id,
+                        displayName: null
+                    })
+                ]);
+            }
+            finally {
+                after.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('allows link_task_context in cloud runtime for URLs', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Cloud context link test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'cloud', 'link_task_context', {
+                id: task.id,
+                path: 'https://example.com/spec',
+                caption: 'Spec'
+            });
+            const after = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const updated = after.getTask(task.id, 'workspace-1');
+                expect(updated?.attachments).toHaveLength(1);
+                expect(updated?.attachments?.[0]).toMatchObject({
+                    path: 'https://example.com/spec',
+                    caption: 'Spec'
+                });
+            }
+            finally {
+                after.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('rejects local file paths for link_task_context in cloud runtime', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Cloud local-path reject test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const result = await callTool(projectRoot, 'cloud', 'link_task_context', {
+                id: task.id,
+                path: 'docs/spec.md'
+            });
+            expect(result.content?.[0]?.text).toContain('link_task_context only supports external http(s) URLs');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('rejects local file paths for link_task_context in local runtime too', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Local local-path reject test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const result = await callTool(projectRoot, 'local', 'link_task_context', {
+                id: task.id,
+                path: 'docs/spec.md'
+            });
+            expect(result.content?.[0]?.text).toContain('link_task_context only supports external http(s) URLs');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('rejects sourcePath for save_task_attachment in cloud runtime', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Cloud sourcePath reject test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const result = await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.id,
+                filename: 'copy.txt',
+                sourcePath: 'docs/source.txt'
+            });
+            expect(result.content?.[0]?.text).toContain('Cloud MCP only supports inline content');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('accepts task references for save_task_attachment', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Reference attachment save test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'reference-note.md',
+                content: '# Saved by reference'
+            });
+            const after = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const updated = after.getTask(task.id, 'workspace-1');
+                expect(updated?.attachments).toHaveLength(1);
+                expect((updated?.attachments?.[0]).fsPath).toContain('workspaces/workspace-1/assets/documents/');
+            }
+            finally {
+                after.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('overwrites canonical attachments in place when overwrite=true', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Overwrite attachment test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'plan.md',
+                content: '# First version'
+            });
+            const before = parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', { id: task.referenceLabel }));
+            const beforeAttachmentId = before.attachments[0]?.attachmentId;
+            const beforeTimestamp = before.attachments[0]?.timestamp;
+            await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'plan.md',
+                content: '# Second version',
+                overwrite: true
+            });
+            const after = parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', { id: task.referenceLabel }));
+            const readBack = parseToolJson(await callTool(projectRoot, 'cloud', 'read_task_attachment', {
+                taskId: task.referenceLabel,
+                attachmentId: beforeAttachmentId
+            }));
+            expect(after.attachments).toHaveLength(1);
+            expect(after.attachments[0]?.attachmentId).toBe(beforeAttachmentId);
+            expect(after.attachments[0]?.originalFilename).toBe('plan.md');
+            expect(after.attachments[0]?.timestamp).not.toBe(beforeTimestamp);
+            expect(readBack.content).toContain('# Second version');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('creates a new attachment when overwrite=true has no canonical filename match', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Overwrite miss test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.id,
+                filename: 'first.md',
+                content: '# First'
+            });
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.id,
+                filename: 'second.md',
+                content: '# Second',
+                overwrite: true
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: task.id }));
+            expect(listed.attachments).toHaveLength(2);
+            expect(listed.attachments.map((attachment) => attachment.originalFilename)).toEqual(['first.md', 'second.md']);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('does not overwrite external URL attachments when overwrite=true', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'External overwrite test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'local', 'link_task_context', {
+                id: task.id,
+                path: 'https://example.com/plan.md',
+                caption: 'plan.md'
+            });
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.id,
+                filename: 'plan.md',
+                content: '# Local plan',
+                overwrite: true
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: task.id }));
+            expect(listed.attachments).toHaveLength(2);
+            expect(listed.attachments.filter((attachment) => attachment.source === 'external')).toHaveLength(1);
+            expect(listed.attachments.filter((attachment) => attachment.source === 'canonical')).toHaveLength(1);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('deletes external URL attachments without touching canonical assets', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Delete external attachment test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'cloud', 'link_task_context', {
+                id: task.referenceLabel,
+                path: 'https://example.com/spec.md',
+                caption: 'spec.md'
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', { id: task.referenceLabel }));
+            const result = parseToolJson(await callTool(projectRoot, 'cloud', 'delete_task_attachment', {
+                taskId: task.referenceLabel,
+                attachmentId: listed.attachments[0]?.attachmentId
+            }));
+            const after = parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', { id: task.referenceLabel }));
+            expect(result.success).toBe(true);
+            expect(result.canonicalAssetDeleted).toBe(false);
+            expect(after.attachments).toEqual([]);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('deletes canonical task attachments and soft-deletes unattached canonical metadata', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Delete canonical attachment test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'delete-me.md',
+                content: '# Delete me'
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', { id: task.referenceLabel }));
+            const attachmentId = listed.attachments[0]?.attachmentId;
+            const assetId = listed.attachments[0]?.assetId;
+            const result = parseToolJson(await callTool(projectRoot, 'cloud', 'delete_task_attachment', {
+                taskId: task.referenceLabel,
+                attachmentId
+            }));
+            const after = parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', { id: task.referenceLabel }));
+            const verifyCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const store = new WorkspaceAssetStore(verifyCore.getDatabaseAdapter(), verifyCore.getTenantId());
+                const deletedAsset = store.get(String(assetId || ''), 'workspace-1');
+                expect(result.success).toBe(true);
+                expect(result.canonicalAssetDeleted).toBe(true);
+                expect(after.attachments).toEqual([]);
+                expect(deletedAsset?.deletedAt).toBeTruthy();
+            }
+            finally {
+                verifyCore.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('deletes annotated attachment sessions when the last linked image attachment is deleted', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const imagePath = path.join(projectRoot, 'fixture-image.png');
+            fs.writeFileSync(imagePath, Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9WnHCqgAAAAASUVORK5CYII=', 'base64'));
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Delete annotated image attachment test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'fixture-image.png',
+                sourcePath: imagePath
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: task.referenceLabel }));
+            const attachmentId = String(listed.attachments[0]?.attachmentId || '');
+            const assetId = String(listed.attachments[0]?.assetId || '');
+            const seededCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                seededCore.createAnnotatedAttachmentSession({
+                    workspaceId: 'workspace-1',
+                    taskId: task.id,
+                    baseImageAssetId: assetId,
+                    title: 'Image review',
+                    annotations: [
+                        { id: 'annotation-1', kind: 'pin', order: 0, instruction: 'Look here', x: 0.3, y: 0.4 },
+                    ],
+                });
+            }
+            finally {
+                seededCore.close();
+            }
+            const result = parseToolJson(await callTool(projectRoot, 'local', 'delete_task_attachment', {
+                taskId: task.referenceLabel,
+                attachmentId
+            }));
+            const verifyCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const activeSessions = verifyCore.listAnnotatedAttachmentSessions({
+                    workspaceId: 'workspace-1',
+                    taskId: task.id,
+                    imageAssetId: assetId,
+                });
+                const allSessions = verifyCore.listAnnotatedAttachmentSessions({
+                    workspaceId: 'workspace-1',
+                    taskId: task.id,
+                    imageAssetId: assetId,
+                    includeDeleted: true,
+                });
+                expect(result.success).toBe(true);
+                expect(result.canonicalAssetDeleted).toBe(true);
+                expect(result.deletedAnnotatedSessions).toBeGreaterThanOrEqual(0);
+                expect(activeSessions).toEqual([]);
+                expect(allSessions[0]?.deletedAt).toBeTruthy();
+            }
+            finally {
+                verifyCore.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('supports overwrite=true for local sourcePath saves', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Source path overwrite test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const sourcePath = path.join(projectRoot, 'notes.md');
+            fs.writeFileSync(sourcePath, '# First source', 'utf8');
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'notes.md',
+                sourcePath: 'notes.md'
+            });
+            const before = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: task.referenceLabel }));
+            fs.writeFileSync(sourcePath, '# Updated source', 'utf8');
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'notes.md',
+                sourcePath: 'notes.md',
+                overwrite: true
+            });
+            const after = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: task.referenceLabel }));
+            expect(after.attachments).toHaveLength(1);
+            expect(after.attachments[0]?.attachmentId).toBe(before.attachments[0]?.attachmentId);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('allows local sourcePath saves from Taskforce-managed tmp/artifact directories', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Taskforce managed source path test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const managedSourcePath = path.join(projectRoot, '.taskforce', 'tmp', 'generated-note.md');
+            fs.mkdirSync(path.dirname(managedSourcePath), { recursive: true });
+            fs.writeFileSync(managedSourcePath, '# Generated in Taskforce tmp', 'utf8');
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'generated-note.md',
+                sourcePath: managedSourcePath
+            });
+            const after = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const updated = after.getTask(task.id, 'workspace-1');
+                expect(updated?.attachments).toHaveLength(1);
+            }
+            finally {
+                after.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('rejects local sourcePath saves from arbitrary paths outside approved sources', async () => {
+        const projectRoot = createProjectRoot();
+        const externalRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-mcp-external-'));
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'External source path reject test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const externalSourcePath = path.join(externalRoot, 'outside.md');
+            fs.writeFileSync(externalSourcePath, '# Outside project and taskforce roots', 'utf8');
+            const result = await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'outside.md',
+                sourcePath: externalSourcePath
+            });
+            expect(result.content?.[0]?.text).toContain('sourcePath must be within project root or a Taskforce-managed attachment source');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+            fs.rmSync(externalRoot, { recursive: true, force: true });
+        }
+    });
+    it('lists task attachments by internal id and task reference', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'List attachments test' }, { workspaceId: 'workspace-1' });
+            const externalTask = core.createTask({ title: 'External attachment list test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.id,
+                filename: 'implementation-plan.txt',
+                content: 'hello attachment'
+            });
+            await callTool(projectRoot, 'local', 'link_task_context', {
+                id: externalTask.id,
+                path: 'https://example.com/spec',
+                caption: 'Spec'
+            });
+            const byId = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: task.id }));
+            const byReference = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: task.referenceLabel }));
+            const external = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: externalTask.id }));
+            expect(byId.taskId).toBe(task.id);
+            expect(byId.referenceLabel).toBe(task.referenceLabel);
+            expect(byId.attachments).toHaveLength(1);
+            expect(byId.attachments[0].mimeType).toBe('text/plain');
+            expect(byId.attachments[0].readableAsText).toBe(true);
+            expect(byId.attachments[0].attachmentId).toBe(byReference.attachments[0].attachmentId);
+            expect(external.attachments).toHaveLength(1);
+            expect(external.attachments[0].source).toBe('external');
+            expect(external.attachments[0].readableAsText).toBe(false);
+            expect(external.attachments[0].caption).toBe('Spec');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('accepts task references for write and batch update tools', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const first = core.createTask({ title: 'First reference write test' }, { workspaceId: 'workspace-1' });
+            const second = core.createTask({ title: 'Second reference write test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'local', 'schedule_task', {
+                id: first.referenceLabel,
+                scheduledDate: '2026-03-24'
+            });
+            await callTool(projectRoot, 'local', 'bulk_assign_tasks', {
+                ids: [first.referenceLabel, second.referenceLabel],
+                assignee: 'agent'
+            });
+            const after = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const firstTask = after.getTask(first.id, 'workspace-1');
+                const secondTask = after.getTask(second.id, 'workspace-1');
+                expect(firstTask?.scheduledDate).toBe('2026-03-24');
+                expect(firstTask?.assignee).toBe('unassigned');
+                expect(secondTask?.assignee).toBe('unassigned');
+            }
+            finally {
+                after.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('maps legacy agent assignee writes to unassigned even when a profile is resolved', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const runtime = createTaskforceMcpServer({
+                projectRoot,
+                runtimeMode: 'local',
+                logStartup: false
+            });
+            const handler = runtime.server._requestHandlers.get('tools/call');
+            if (!handler) {
+                throw new Error('tools/call handler not registered');
+            }
+            const resolved = parseToolJson(await handler({
+                jsonrpc: '2.0',
+                id: 'test-tools-call-resolve-profile',
+                method: 'tools/call',
+                params: {
+                    name: 'resolve_profile',
+                    arguments: {
+                        name: 'Codex',
+                        icon: 'Bot',
+                        color: '#ef6c00'
+                    }
+                }
+            }, {}));
+            const created = parseToolJson(await handler({
+                jsonrpc: '2.0',
+                id: 'test-tools-call-create-task',
+                method: 'tools/call',
+                params: {
+                    name: 'create_task',
+                    arguments: {
+                        title: 'Profile-backed assignment',
+                        assignee: 'agent'
+                    }
+                }
+            }, {}));
+            expect(created.assignee).toBe('unassigned');
+            expect(created.createdBy).toBe(resolved.profile.id);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('logs profile-backed MCP task creation with the resolved AI profile instead of generic agent', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const runtime = createTaskforceMcpServer({
+                projectRoot,
+                runtimeMode: 'local',
+                logStartup: false
+            });
+            const handler = runtime.server._requestHandlers.get('tools/call');
+            if (!handler) {
+                throw new Error('tools/call handler not registered');
+            }
+            const resolved = parseToolJson(await handler({
+                jsonrpc: '2.0',
+                id: 'test-tools-call-resolve-profile-for-created-by',
+                method: 'tools/call',
+                params: {
+                    name: 'resolve_profile',
+                    arguments: {
+                        name: 'Codex',
+                        icon: 'Bot',
+                        color: '#ef6c00'
+                    }
+                }
+            }, {}));
+            const created = parseToolJson(await handler({
+                jsonrpc: '2.0',
+                id: 'test-tools-call-create-task-created-by',
+                method: 'tools/call',
+                params: {
+                    name: 'create_task',
+                    arguments: {
+                        title: 'Profile-backed createdBy'
+                    }
+                }
+            }, {}));
+            expect(created.createdBy).toBe(resolved.profile.id);
+            expect(created.createdByActor).toEqual(expect.objectContaining({
+                id: resolved.profile.id,
+                label: 'Codex',
+                username: resolved.profile.username
+            }));
+            expect(created.taskEvents).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    action: 'task-created',
+                    actor: resolved.profile.id,
+                    actorType: 'ai',
+                    actorProfile: expect.objectContaining({
+                        id: resolved.profile.id,
+                        label: 'Codex',
+                        username: resolved.profile.username
+                    })
+                })
+            ]));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('returns empty attachments for tasks without context files', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'No attachments test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const payload = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: task.id }));
+            expect(payload.attachments).toEqual([]);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('reads markdown task attachments as inline text in local and cloud runtimes', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Read attachment test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.id,
+                filename: 'notes.md',
+                content: '# Heading\nBody'
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: task.id }));
+            const attachmentId = listed.attachments[0]?.attachmentId;
+            expect(attachmentId).toBeTruthy();
+            const localRead = parseToolJson(await callTool(projectRoot, 'local', 'read_task_attachment', { taskId: task.id, attachmentId }));
+            const cloudRead = parseToolJson(await callTool(projectRoot, 'cloud', 'read_task_attachment', { taskId: task.referenceLabel, attachmentId }));
+            expect(localRead.format).toBe('text');
+            expect(localRead.truncated).toBe(false);
+            expect(localRead.content).toContain('# Heading');
+            expect(cloudRead.content).toContain('Body');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('returns canonical document workflow hints for markdown task attachments', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Canonical document attachment hints test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'design-notes.md',
+                content: '# Design notes\nBody'
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', { id: task.referenceLabel }));
+            const attachment = listed.attachments[0];
+            expect(attachment?.kind).toBe('document');
+            expect(attachment?.documentId).toBeTruthy();
+            expect(attachment?.referenceLabel).toMatch(/^D-\d+$/);
+            expect(attachment?.preferredNextTool).toBe('get_document');
+            expect(attachment?.preferredWorkflow).toBe('canonical_document');
+            expect(attachment?.suggestedArgs?.documentId).toBe(attachment?.referenceLabel);
+            expect(attachment?.guidance).toContain('canonical document');
+            const metadata = parseToolJson(await callTool(projectRoot, 'cloud', 'read_task_attachment', {
+                taskId: task.referenceLabel,
+                attachmentId: attachment?.attachmentId,
+                format: 'metadata'
+            }));
+            expect(metadata.format).toBe('metadata');
+            expect(metadata.attachment.documentId).toBe(attachment?.documentId);
+            expect(metadata.attachment.preferredNextTool).toBe('get_document');
+            expect(metadata.attachment.preferredWorkflow).toBe('canonical_document');
+            expect(metadata.attachment.suggestedArgs?.documentId).toBe(attachment?.referenceLabel);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('does not assign document references or canonical document hints to txt task attachments', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Plain text attachment invariants' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'design-notes.txt',
+                content: 'plain text note'
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', { id: task.referenceLabel }));
+            const attachment = listed.attachments[0];
+            expect(attachment?.kind).toBe('file');
+            expect(attachment?.referenceLabel || null).toBeNull();
+            expect(attachment?.preferredNextTool).toBeUndefined();
+            expect(attachment?.preferredWorkflow).toBeUndefined();
+            expect(attachment?.suggestedArgs).toBeUndefined();
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('returns download metadata for binary attachments instead of inline text', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Binary attachment test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.id,
+                filename: 'proof.png',
+                content: 'fake-image-bits'
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: task.id }));
+            const attachmentId = listed.attachments[0]?.attachmentId;
+            const response = parseToolJson(await callTool(projectRoot, 'cloud', 'read_task_attachment', { taskId: task.id, attachmentId }));
+            expect(listed.attachments[0]?.mimeType).toBe('image/png');
+            expect(listed.attachments[0]?.readableAsText).toBe(false);
+            expect(response.format).toBe('download');
+            expect(response.reason).toBe('binary_file');
+            expect(response.downloadUrl).toContain('download=1');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('rejects inline reads for quarantined and pending attachments', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const pendingTask = core.createTask({ title: 'Pending attachment test' }, { workspaceId: 'workspace-1' });
+            const infectedTask = core.createTask({ title: 'Infected attachment test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: pendingTask.id,
+                filename: 'pending.md',
+                content: '# Pending'
+            });
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: infectedTask.id,
+                filename: 'infected.md',
+                content: '# Infected'
+            });
+            const dbCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const store = new WorkspaceAssetStore(dbCore.getDatabaseAdapter(), dbCore.getTenantId());
+                const pendingAttachment = dbCore.getTask(pendingTask.id, 'workspace-1')?.attachments?.[0];
+                const infectedAttachment = dbCore.getTask(infectedTask.id, 'workspace-1')?.attachments?.[0];
+                const pendingAsset = store.get(String(pendingAttachment?.assetId || ''), 'workspace-1');
+                const infectedAsset = store.get(String(infectedAttachment?.assetId || ''), 'workspace-1');
+                expect(pendingAsset).toBeTruthy();
+                expect(infectedAsset).toBeTruthy();
+                store.upsertAsset({
+                    ...pendingAsset,
+                    scanStatus: 'pending'
+                });
+                store.upsertAsset({
+                    ...infectedAsset,
+                    scanStatus: 'infected'
+                });
+            }
+            finally {
+                dbCore.close();
+            }
+            const pendingList = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: pendingTask.id }));
+            const infectedList = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: infectedTask.id }));
+            const pendingRead = await callTool(projectRoot, 'cloud', 'read_task_attachment', {
+                taskId: pendingTask.id,
+                attachmentId: pendingList.attachments[0]?.attachmentId
+            });
+            const infectedRead = await callTool(projectRoot, 'cloud', 'read_task_attachment', {
+                taskId: infectedTask.id,
+                attachmentId: infectedList.attachments[0]?.attachmentId
+            });
+            expect(pendingRead.content?.[0]?.text).toContain('Attachment scan pending');
+            expect(infectedRead.content?.[0]?.text).toContain('Attachment is quarantined');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('returns a readable diagnostic when an r2 attachment cannot be read in this runtime', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'R2 diagnostic test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.id,
+                filename: 'diagnostic.txt',
+                content: 'hello'
+            });
+            const dbCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const store = new WorkspaceAssetStore(dbCore.getDatabaseAdapter(), dbCore.getTenantId());
+                const attachment = dbCore.getTask(task.id, 'workspace-1')?.attachments?.[0];
+                const asset = store.get(String(attachment?.assetId || ''), 'workspace-1');
+                expect(asset).toBeTruthy();
+                store.upsertAsset({
+                    ...asset,
+                    storageProvider: 'r2'
+                });
+            }
+            finally {
+                dbCore.close();
+            }
+            const listed = parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', { id: task.id }));
+            const result = await callTool(projectRoot, 'cloud', 'read_task_attachment', {
+                taskId: task.id,
+                attachmentId: listed.attachments[0]?.attachmentId
+            });
+            expect(result.content?.[0]?.text).toContain('Attachment read failed from R2 because object storage is not configured');
+            expect(result.content?.[0]?.text).toContain('attachmentId=');
+            expect(result.content?.[0]?.text).toContain('storageKey=');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('preserves attachment ordering in get_task_attachments', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Attachment order test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.id,
+                filename: 'first.md',
+                content: '# First',
+                caption: 'First'
+            });
+            await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.id,
+                filename: 'second.md',
+                content: '# Second',
+                caption: 'Second'
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'local', 'get_task_attachments', { id: task.id }));
+            expect(listed.attachments.map((attachment) => attachment.caption)).toEqual(['First', 'Second']);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+});
+describe('Taskforce MCP annotated attachment tools', () => {
+    let previousGateEnabled = false;
+    beforeEach(() => {
+        previousGateEnabled = APP_GATE_DEFINITIONS[ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY].enabled;
+        APP_GATE_DEFINITIONS[ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY].enabled = true;
+    });
+    afterEach(() => {
+        APP_GATE_DEFINITIONS[ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY].enabled = previousGateEnabled;
+    });
+    it('lists annotated attachment sessions and reads payloads', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { task, session } = seedAnnotatedAttachmentFixture(projectRoot);
+            const sessionsResult = parseToolJson(await callTool(projectRoot, 'local', 'get_annotated_attachment_sessions', {
+                taskId: task.referenceLabel || task.id,
+            }, { workspaceId: 'workspace-1' }));
+            expect(sessionsResult.taskId).toBe(task.id);
+            expect(sessionsResult.sessions).toHaveLength(1);
+            expect(sessionsResult.sessions[0]).toMatchObject({
+                id: session.id,
+                title: 'Fixture session',
+            });
+            const imageResult = parseToolJson(await callTool(projectRoot, 'local', 'get_image', {
+                imageId: 'I-1',
+            }, { workspaceId: 'workspace-1' }));
+            expect(imageResult.image).toMatchObject({
+                assetId: 'asset-annotated-1',
+                referenceLabel: 'I-1',
+            });
+            expect(imageResult.linkedTasks[0]).toMatchObject({
+                taskId: task.id,
+                referenceLabel: task.referenceLabel,
+            });
+            expect(imageResult.linkedTasks[0]?.sessions[0]?.id).toBe(session.id);
+            const imageSessionsResult = parseToolJson(await callTool(projectRoot, 'local', 'get_annotated_attachment_sessions', {
+                imageId: 'I-1',
+            }, { workspaceId: 'workspace-1' }));
+            expect(imageSessionsResult.image).toMatchObject({
+                assetId: 'asset-annotated-1',
+                referenceLabel: 'I-1',
+            });
+            expect(imageSessionsResult.tasks[0]?.taskId).toBe(task.id);
+            expect(imageSessionsResult.tasks[0]?.sessions[0]?.id).toBe(session.id);
+            const payloadResult = parseToolJson(await callTool(projectRoot, 'local', 'read_annotated_attachment_payload', {
+                sessionId: session.id,
+            }, { workspaceId: 'workspace-1' }));
+            expect(payloadResult).toMatchObject({
+                taskId: task.id,
+                sessionId: session.id,
+                title: 'Fixture session',
+                image: {
+                    assetId: 'asset-annotated-1',
+                    referenceLabel: 'I-1',
+                },
+            });
+            expect(payloadResult.annotations[0].id).toBe('annotation-1');
+            expect(payloadResult.annotations[0].kind).toBe('pin');
+            expect(payloadResult.annotations[0].cropHint.x).toBeCloseTo(0.16, 10);
+            expect(payloadResult.annotations[0].cropHint.y).toBeCloseTo(0.31, 10);
+            expect(payloadResult.annotations[0].cropHint.width).toBeCloseTo(0.18, 10);
+            expect(payloadResult.annotations[0].cropHint.height).toBeCloseTo(0.18, 10);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('includes unattached image note sessions in image-centric MCP reads', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { task, session } = seedAnnotatedAttachmentFixture(projectRoot);
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce'),
+            });
+            try {
+                core.createAnnotatedAttachmentSession({
+                    workspaceId: 'workspace-1',
+                    taskId: null,
+                    baseImageAssetId: 'asset-annotated-1',
+                    title: 'Unattached image review',
+                    globalInstruction: 'Keep this separate from task notes.',
+                    actorId: 'owner-1',
+                    annotations: [
+                        {
+                            id: 'annotation-unattached-1',
+                            kind: 'pin',
+                            order: 0,
+                            markerType: 'review',
+                            instruction: 'Review the unattached image state.',
+                            x: 0.5,
+                            y: 0.5,
+                        },
+                    ],
+                });
+            }
+            finally {
+                core.close();
+            }
+            const imageResult = parseToolJson(await callTool(projectRoot, 'local', 'get_image', {
+                imageId: 'I-1',
+            }, { workspaceId: 'workspace-1' }));
+            expect(imageResult.image).toMatchObject({
+                assetId: 'asset-annotated-1',
+                referenceLabel: 'I-1',
+            });
+            expect(imageResult.linkedTasks[0]?.taskId).toBe(task.id);
+            expect(imageResult.linkedTasks[0]?.sessions[0]?.id).toBe(session.id);
+            expect(imageResult.unattachedSessions).toHaveLength(1);
+            expect(imageResult.unattachedSessions[0]).toMatchObject({
+                title: 'Unattached image review',
+            });
+            const imageSessionsResult = parseToolJson(await callTool(projectRoot, 'local', 'get_annotated_attachment_sessions', {
+                imageId: 'I-1',
+            }, { workspaceId: 'workspace-1' }));
+            expect(imageSessionsResult.image).toMatchObject({
+                assetId: 'asset-annotated-1',
+                referenceLabel: 'I-1',
+            });
+            expect(imageSessionsResult.tasks[0]?.taskId).toBe(task.id);
+            expect(imageSessionsResult.tasks[0]?.sessions[0]?.id).toBe(session.id);
+            expect(imageSessionsResult.unattachedSessions).toHaveLength(1);
+            expect(imageSessionsResult.unattachedSessions[0]).toMatchObject({
+                title: 'Unattached image review',
+            });
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('searches canonical images by reference label and filename fragment', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            seedAnnotatedAttachmentFixture(projectRoot);
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const assetStore = core.getWorkspaceAssetStore();
+                assetStore.upsertAsset({
+                    assetId: 'asset-annotated-2',
+                    workspaceId: 'workspace-1',
+                    kind: 'image',
+                    logicalName: 'Roadmap screenshot',
+                    originalFilename: 'roadmap-screenshot.png',
+                    mimeType: 'image/png',
+                    storageProvider: 'local',
+                    storageKey: 'workspaces/workspace-1/assets/images/asset-annotated-2-roadmap-screenshot.png',
+                    contentSha256: 'sha-annotated-2',
+                    sizeBytes: 768,
+                    referenceNumber: 2,
+                });
+            }
+            finally {
+                core.close();
+            }
+            const byReference = parseToolJson(await callTool(projectRoot, 'local', 'search_images', {
+                query: 'I-1',
+            }, { workspaceId: 'workspace-1' }));
+            expect(byReference.results[0]).toMatchObject({
+                image: {
+                    assetId: 'asset-annotated-1',
+                    referenceLabel: 'I-1',
+                },
+                nextTool: 'get_image',
+                suggestedArgs: { imageId: 'I-1' },
+            });
+            expect(byReference.results[0]?.matchedOn).toContain('referenceLabel');
+            expect(byReference.guidance).toContain('call get_image');
+            const byFilename = parseToolJson(await callTool(projectRoot, 'local', 'search_images', {
+                query: 'roadmap-screenshot',
+            }, { workspaceId: 'workspace-1' }));
+            expect(byFilename.results[0]).toMatchObject({
+                image: {
+                    assetId: 'asset-annotated-2',
+                    referenceLabel: 'I-2',
+                },
+                suggestedArgs: { imageId: 'I-2' },
+            });
+            expect(byFilename.results[0]?.matchedOn).toContain('originalFilename');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('nudges agents toward search_images when exact image lookup fails', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            seedAnnotatedAttachmentFixture(projectRoot);
+            const result = await callTool(projectRoot, 'local', 'get_image', {
+                imageId: 'roadmap image',
+            }, { workspaceId: 'workspace-1' });
+            expect(result.isError).toBe(true);
+            expect(result.content?.[0]?.text).toContain('call search_images first');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('creates image-note sessions and mutates markers through MCP', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { task } = seedAnnotatedAttachmentFixture(projectRoot);
+            const createdSession = parseToolJson(await callTool(projectRoot, 'local', 'create_annotated_attachment_session', {
+                imageId: 'asset-annotated-1',
+                taskId: task.id,
+                title: 'AI walkthrough',
+                sessionInstruction: 'Review the flow in order.',
+            }, { workspaceId: 'workspace-1' }));
+            expect(createdSession.image.assetId).toBe('asset-annotated-1');
+            expect(createdSession.session.title).toBe('AI walkthrough');
+            expect(createdSession.session.globalInstruction).toBe('Review the flow in order.');
+            expect(createdSession.session.annotations).toHaveLength(0);
+            const addedMarker = parseToolJson(await callTool(projectRoot, 'local', 'add_annotated_attachment_marker', {
+                sessionId: createdSession.session.id,
+                kind: 'box',
+                instruction: 'Focus attention on this panel.',
+                instructionType: 'change',
+                x: 0.2,
+                y: 0.3,
+                width: 0.25,
+                height: 0.15,
+            }, { workspaceId: 'workspace-1' }));
+            expect(addedMarker.marker.kind).toBe('box');
+            expect(addedMarker.marker.markerType).toBe('change');
+            expect(addedMarker.session.annotations).toHaveLength(1);
+            const updatedMarker = parseToolJson(await callTool(projectRoot, 'local', 'update_annotated_attachment_marker', {
+                sessionId: createdSession.session.id,
+                markerId: addedMarker.marker.id,
+                instruction: 'Focus attention on this primary panel.',
+                instructionType: 'review',
+                width: 0.3,
+            }, { workspaceId: 'workspace-1' }));
+            expect(updatedMarker.marker.instruction).toBe('Focus attention on this primary panel.');
+            expect(updatedMarker.marker.markerType).toBe('review');
+            expect(updatedMarker.marker.width).toBeCloseTo(0.3, 10);
+            const updatedSession = parseToolJson(await callTool(projectRoot, 'local', 'update_annotated_attachment_session', {
+                sessionId: createdSession.session.id,
+                title: 'AI walkthrough v2',
+                sessionInstruction: 'Answer each marker in order.',
+            }, { workspaceId: 'workspace-1' }));
+            expect(updatedSession.session.title).toBe('AI walkthrough v2');
+            expect(updatedSession.session.globalInstruction).toBe('Answer each marker in order.');
+            const deletedMarker = parseToolJson(await callTool(projectRoot, 'local', 'delete_annotated_attachment_marker', {
+                sessionId: createdSession.session.id,
+                markerId: addedMarker.marker.id,
+            }, { workspaceId: 'workspace-1' }));
+            expect(deletedMarker.deletedMarkerId).toBe(addedMarker.marker.id);
+            expect(deletedMarker.session.annotations).toHaveLength(0);
+            const verifyCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const persisted = verifyCore.getAnnotatedAttachmentSession({
+                    workspaceId: 'workspace-1',
+                    sessionId: createdSession.session.id,
+                });
+                expect(persisted?.title).toBe('AI walkthrough v2');
+                expect(persisted?.globalInstruction).toBe('Answer each marker in order.');
+                expect(persisted?.annotations).toHaveLength(0);
+            }
+            finally {
+                verifyCore.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('bulk adds and reorders image-note markers through MCP', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { task, session } = seedAnnotatedAttachmentFixture(projectRoot);
+            const bulkAdded = parseToolJson(await callTool(projectRoot, 'local', 'bulk_add_annotated_attachment_markers', {
+                sessionId: session.id,
+                markers: [
+                    {
+                        kind: 'pin',
+                        instruction: 'Start here.',
+                        instructionType: 'review',
+                        x: 0.1,
+                        y: 0.15,
+                    },
+                    {
+                        kind: 'arrow',
+                        instruction: 'Move toward this action.',
+                        instructionType: 'change',
+                        x: 0.2,
+                        y: 0.25,
+                        x2: 0.4,
+                        y2: 0.45,
+                    },
+                ],
+            }, { workspaceId: 'workspace-1' }));
+            expect(bulkAdded.markers).toHaveLength(2);
+            expect(bulkAdded.session.annotations).toHaveLength(3);
+            expect(bulkAdded.session.annotations.map((annotation) => annotation.order)).toEqual([0, 1, 2]);
+            const movedMarkerId = bulkAdded.markers[1]?.id;
+            const reordered = parseToolJson(await callTool(projectRoot, 'local', 'reorder_annotated_attachment_marker', {
+                sessionId: session.id,
+                markerId: movedMarkerId,
+                toIndex: 0,
+            }, { workspaceId: 'workspace-1' }));
+            expect(reordered.session.annotations.map((annotation) => annotation.id)).toEqual([
+                movedMarkerId,
+                'annotation-1',
+                bulkAdded.markers[0]?.id,
+            ]);
+            expect(reordered.session.annotations.map((annotation) => annotation.order)).toEqual([0, 1, 2]);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('deletes image-note sessions through MCP', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { session } = seedAnnotatedAttachmentFixture(projectRoot);
+            const deleted = parseToolJson(await callTool(projectRoot, 'local', 'delete_annotated_attachment_session', {
+                sessionId: session.id,
+            }, { workspaceId: 'workspace-1' }));
+            expect(deleted.deleted).toBe(true);
+            expect(deleted.deletedSessionId).toBe(session.id);
+            expect(deleted.image?.assetId).toBe('asset-annotated-1');
+            const verifyCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const persisted = verifyCore.getAnnotatedAttachmentSession({
+                    workspaceId: 'workspace-1',
+                    sessionId: session.id,
+                });
+                expect(persisted).toBeNull();
+            }
+            finally {
+                verifyCore.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('reviews an image through the helper by creating or reusing a session', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { task, session } = seedAnnotatedAttachmentFixture(projectRoot);
+            const created = parseToolJson(await callTool(projectRoot, 'local', 'review_image', {
+                imageId: 'asset-annotated-1',
+                taskId: task.id,
+                title: 'AI image review',
+                sessionInstruction: 'Address each comment in order.',
+                markers: [
+                    {
+                        kind: 'pin',
+                        instruction: 'Check this entry point.',
+                        x: 0.22,
+                        y: 0.33,
+                    },
+                    {
+                        kind: 'arrow',
+                        instruction: 'Then move to this control.',
+                        instructionType: 'change',
+                        x: 0.3,
+                        y: 0.4,
+                        x2: 0.48,
+                        y2: 0.51,
+                    },
+                ],
+            }, { workspaceId: 'workspace-1' }));
+            expect(created.session.title).toBe('AI image review');
+            expect(created.session.globalInstruction).toBe('Address each comment in order.');
+            expect(created.markers).toHaveLength(2);
+            expect(created.session.annotations).toHaveLength(2);
+            const reused = parseToolJson(await callTool(projectRoot, 'local', 'review_image', {
+                imageId: 'asset-annotated-1',
+                taskId: task.id,
+                sessionId: session.id,
+                sessionInstruction: 'Reply in sequence.',
+                markers: [
+                    {
+                        kind: 'text-note',
+                        instruction: 'Summarize the overall issue here.',
+                        x: 0.55,
+                        y: 0.6,
+                    },
+                ],
+            }, { workspaceId: 'workspace-1' }));
+            expect(reused.session.id).toBe(session.id);
+            expect(reused.markers).toHaveLength(1);
+            expect(reused.session.annotations).toHaveLength(2);
+            const verifyCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const reusedPersisted = verifyCore.getAnnotatedAttachmentSession({
+                    workspaceId: 'workspace-1',
+                    sessionId: session.id,
+                });
+                expect(reusedPersisted?.globalInstruction).toBe('Reply in sequence.');
+                expect(reusedPersisted?.annotations).toHaveLength(2);
+            }
+            finally {
+                verifyCore.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('rejects annotated attachment MCP reads when the feature gate is disabled', async () => {
+        APP_GATE_DEFINITIONS[ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY].enabled = false;
+        const projectRoot = createProjectRoot();
+        try {
+            const { task } = seedAnnotatedAttachmentFixture(projectRoot);
+            const result = await callTool(projectRoot, 'local', 'get_annotated_attachment_sessions', {
+                taskId: task.id,
+            }, { workspaceId: 'workspace-1' });
+            expect(result.isError).toBe(true);
+            expect(result.content?.[0]?.text).toContain('Annotated attachments are unavailable for this workspace.');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+});
+describe('Taskforce MCP document review tools', () => {
+    it('gets one canonical document using D-123 identifiers', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { asset } = seedDocumentReviewFixture(projectRoot);
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const task = core.createTask({ title: 'Document link fixture' }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+                core.getWorkspaceAssetStore().upsertLink({
+                    workspaceId: 'workspace-1',
+                    assetId: asset.assetId,
+                    taskId: task.id,
+                    role: 'attachment',
+                    displayName: 'Linked rollout plan',
+                });
+            }
+            finally {
+                core.close();
+            }
+            const result = parseToolJson(await callTool(projectRoot, 'local', 'get_document', {
+                documentId: 'D-123',
+            }, { workspaceId: 'workspace-1' }));
+            expect(result.document).toMatchObject({
+                assetId: asset.assetId,
+                referenceLabel: 'D-123',
+                apiUrl: `/api/taskforce/documents/${asset.assetId}/content`,
+            });
+            expect(result.linkedTasks).toHaveLength(1);
+            expect(result.linkedTasks[0]).toMatchObject({
+                caption: 'Linked rollout plan',
+            });
+            expect(result.reviewSessions).toHaveLength(1);
+            expect(result.reviewSessions[0]).toMatchObject({
+                title: 'Fixture review',
+                status: 'open',
+                commentCount: 1,
+            });
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('lists and reads document review sessions using D-123 identifiers', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { asset, session } = seedDocumentReviewFixture(projectRoot);
+            const sessionsResult = parseToolJson(await callTool(projectRoot, 'local', 'get_document_review_sessions', {
+                documentId: 'D-123',
+            }, { workspaceId: 'workspace-1' }));
+            expect(sessionsResult.document).toMatchObject({
+                assetId: asset.assetId,
+                referenceLabel: 'D-123',
+            });
+            expect(sessionsResult.sessions).toHaveLength(1);
+            expect(sessionsResult.sessions[0]).toMatchObject({
+                id: session.id,
+                title: 'Fixture review',
+            });
+            const sessionResult = parseToolJson(await callTool(projectRoot, 'local', 'get_document_review_session', {
+                sessionId: session.id,
+            }, { workspaceId: 'workspace-1' }));
+            expect(sessionResult.document).toMatchObject({
+                assetId: asset.assetId,
+                referenceLabel: 'D-123',
+            });
+            expect(sessionResult.session.id).toBe(session.id);
+            expect(sessionResult.session.comments[0]?.body).toBe('Please tighten the rollout section.');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('reads canonical document content directly through MCP in local and cloud runtimes', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { asset } = seedDocumentReviewFixture(projectRoot);
+            const localResult = parseToolJson(await callTool(projectRoot, 'local', 'read_document_content', {
+                documentId: 'D-123',
+            }, { workspaceId: 'workspace-1' }));
+            const cloudResult = parseToolJson(await callTool(projectRoot, 'cloud', 'read_document_content', {
+                documentId: asset.documentId,
+            }, { workspaceId: 'workspace-1' }));
+            expect(localResult.document).toMatchObject({
+                assetId: asset.assetId,
+                referenceLabel: 'D-123',
+            });
+            expect(localResult.format).toBe('text');
+            expect(localResult.truncated).toBe(false);
+            expect(localResult.content).toContain('# Fixture plan');
+            expect(localResult.content).toContain('Please tighten the rollout section.');
+            expect(cloudResult.document).toMatchObject({
+                assetId: asset.assetId,
+                referenceLabel: 'D-123',
+            });
+            expect(cloudResult.format).toBe('text');
+            expect(cloudResult.content).toContain('# Fixture plan');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('searches canonical documents by reference label and filename fragment', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { asset } = seedDocumentReviewFixture(projectRoot);
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const assetStore = core.getWorkspaceAssetStore();
+                const { basePath } = core.getPaths();
+                const storageKey = 'workspaces/workspace-1/assets/documents/asset-document-2-architecture-notes.md';
+                const absolutePath = path.join(basePath, storageKey);
+                fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+                fs.writeFileSync(absolutePath, '# Architecture notes\n\nSecondary fixture.\n', 'utf8');
+                assetStore.upsertAsset({
+                    assetId: 'asset-document-2',
+                    workspaceId: 'workspace-1',
+                    kind: 'document',
+                    logicalName: 'Architecture notes',
+                    originalFilename: 'architecture-notes.md',
+                    mimeType: 'text/markdown',
+                    storageProvider: 'local',
+                    storageKey,
+                    contentSha256: 'sha-document-2',
+                    sizeBytes: 420,
+                    documentId: 'doc-architecture-2',
+                    referenceNumber: 124,
+                    version: 1,
+                    isLatest: true,
+                });
+            }
+            finally {
+                core.close();
+            }
+            const byReference = parseToolJson(await callTool(projectRoot, 'cloud', 'search_documents', {
+                query: 'D-123',
+            }, { workspaceId: 'workspace-1' }));
+            expect(byReference.query).toBe('D-123');
+            expect(byReference.results[0]).toMatchObject({
+                document: {
+                    assetId: asset.assetId,
+                    referenceLabel: 'D-123',
+                },
+                nextTool: 'get_document',
+                suggestedArgs: { documentId: 'D-123' },
+            });
+            expect(byReference.results[0]?.matchedOn).toContain('referenceLabel');
+            expect(byReference.guidance).toContain('call get_document');
+            const byFilename = parseToolJson(await callTool(projectRoot, 'cloud', 'search_documents', {
+                query: 'architecture-notes',
+            }, { workspaceId: 'workspace-1' }));
+            expect(byFilename.results[0]).toMatchObject({
+                document: {
+                    assetId: 'asset-document-2',
+                    referenceLabel: 'D-124',
+                },
+                suggestedArgs: { documentId: 'D-124' },
+            });
+            expect(byFilename.results[0]?.matchedOn).toContain('originalFilename');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('nudges agents toward search_documents when exact document lookup fails', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            seedDocumentReviewFixture(projectRoot);
+            const result = await callTool(projectRoot, 'cloud', 'get_document', {
+                documentId: 'rollout plan',
+            }, { workspaceId: 'workspace-1' });
+            expect(result.isError).toBe(true);
+            expect(result.content?.[0]?.text).toContain('call search_documents first');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('tells agents exactly how to read document content from get_document', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            seedDocumentReviewFixture(projectRoot);
+            const result = parseToolJson(await callTool(projectRoot, 'cloud', 'get_document', {
+                documentId: 'D-123',
+            }, { workspaceId: 'workspace-1' }));
+            expect(result.document.referenceLabel).toBe('D-123');
+            expect(result.readContent).toMatchObject({
+                available: true,
+                nextTool: 'read_document_content',
+                suggestedArgs: { documentId: 'D-123' },
+            });
+            expect(result.readContent.guidance).toContain('call read_document_content');
+            expect(result.readContent.reviewNext).toMatchObject({
+                helperTool: 'review_document',
+                listTool: 'get_document_review_sessions',
+                createTool: 'create_document_review_session',
+                commentTool: 'add_document_review_comment',
+            });
+            expect(result.readContent.reviewNext.guidance).toContain('After reading the document body');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('creates, updates, and comments on document review sessions through MCP', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { asset } = seedDocumentReviewFixture(projectRoot);
+            const created = parseToolJson(await callTool(projectRoot, 'cloud', 'create_document_review_session', {
+                documentId: asset.assetId,
+                title: 'AI Review Round',
+            }, { workspaceId: 'workspace-1' }));
+            expect(created.document.assetId).toBe(asset.assetId);
+            expect(created.session.title).toBe('AI Review Round');
+            expect(created.session.status).toBe('open');
+            const updated = parseToolJson(await callTool(projectRoot, 'cloud', 'update_document_review_session', {
+                sessionId: created.session.id,
+                status: 'resolved',
+            }, { workspaceId: 'workspace-1' }));
+            expect(updated.session.id).toBe(created.session.id);
+            expect(updated.session.status).toBe('resolved');
+            const clearedTitle = parseToolJson(await callTool(projectRoot, 'cloud', 'update_document_review_session', {
+                sessionId: created.session.id,
+                title: null,
+            }, { workspaceId: 'workspace-1' }));
+            expect(clearedTitle.session.id).toBe(created.session.id);
+            expect(clearedTitle.session.title).toBeNull();
+            const commented = parseToolJson(await callTool(projectRoot, 'cloud', 'add_document_review_comment', {
+                sessionId: created.session.id,
+                body: 'Cloud reviewer follow-up.',
+                anchor: { kind: 'document' },
+            }, { workspaceId: 'workspace-1' }));
+            expect(commented.session.id).toBe(created.session.id);
+            expect(commented.session.comments.at(-1)).toMatchObject({
+                body: 'Cloud reviewer follow-up.',
+                anchor: { kind: 'document' },
+            });
+            const updatedComment = parseToolJson(await callTool(projectRoot, 'cloud', 'update_document_review_comment', {
+                sessionId: created.session.id,
+                commentId: commented.session.comments.at(-1)?.id,
+                body: 'Cloud reviewer edited follow-up.',
+                anchor: null,
+            }, { workspaceId: 'workspace-1' }));
+            expect(updatedComment.session.id).toBe(created.session.id);
+            expect(updatedComment.session.comments.at(-1)).toMatchObject({
+                body: 'Cloud reviewer edited follow-up.',
+                anchor: null,
+            });
+            const deletedComment = parseToolJson(await callTool(projectRoot, 'cloud', 'delete_document_review_comment', {
+                sessionId: created.session.id,
+                commentId: commented.session.comments.at(-1)?.id,
+            }, { workspaceId: 'workspace-1' }));
+            expect(deletedComment.session.id).toBe(created.session.id);
+            expect(deletedComment.session.comments.some((comment) => comment.id === commented.session.comments.at(-1)?.id)).toBe(false);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('reviews a document through the helper by reusing a single open session', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { asset, session } = seedDocumentReviewFixture(projectRoot);
+            const result = parseToolJson(await callTool(projectRoot, 'cloud', 'review_document', {
+                documentId: 'D-123',
+                comments: [
+                    { body: 'Please add an owner fallback note.' },
+                    { body: 'Clarify whether done remains active.' }
+                ],
+            }, { workspaceId: 'workspace-1' }));
+            expect(result.document).toMatchObject({
+                assetId: asset.assetId,
+                referenceLabel: 'D-123',
+            });
+            expect(result.review.sessionId).toBe(session.id);
+            expect(result.review.sessionAction).toBe('reused');
+            expect(result.review.postedCommentIds).toHaveLength(2);
+            expect(result.comments.map((comment) => comment.body)).toEqual([
+                'Please add an owner fallback note.',
+                'Clarify whether done remains active.'
+            ]);
+            expect(result.session.comments.at(-1)?.body).toBe('Clarify whether done remains active.');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('creates a new review session through review_document when open-session reuse is ambiguous', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { asset } = seedDocumentReviewFixture(projectRoot);
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            core.createDocumentReviewSession({
+                workspaceId: 'workspace-1',
+                assetId: asset.assetId,
+                title: 'Second open review',
+                actorId: 'owner-1',
+            });
+            core.close();
+            const result = parseToolJson(await callTool(projectRoot, 'cloud', 'review_document', {
+                documentId: asset.documentId,
+                title: 'Fresh helper review',
+                comments: [{ body: 'Open sessions were ambiguous, so create a fresh one.' }],
+            }, { workspaceId: 'workspace-1' }));
+            expect(result.review.sessionAction).toBe('created');
+            expect(result.review.postedCommentIds).toHaveLength(1);
+            expect(result.session.title).toBe('Fresh helper review');
+            expect(result.session.comments.at(-1)?.body).toBe('Open sessions were ambiguous, so create a fresh one.');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+});