@taskforcehq/taskforce 0.3.305 → 0.3.307

package/dist/mcp/runtime.test.js

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import { createHash, randomBytes } from 'crypto';
 import { createTaskforceMcpServer } from './runtime';
 import { MCP_TOOL_REGISTRY } from './toolRegistry';
 import { TaskforceCore, TaskforceRuleError } from '../core/Taskforce';
@@ -17,6 +18,7 @@ function createRuntime(projectRoot, runtimeMode, options) {
             ? {
                 scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
                 userId: options?.authUserId || 'owner-1',
+                tokenId: options?.authTokenId || null,
                 actorType: 'oauth',
                 aiProfileToken: options?.authAiProfileToken || null,
                 aiProfileName: options?.authAiProfileName || null,
@@ -160,6 +162,34 @@ function parseToolJson(result) {
     expect(text).toBeTruthy();
     return JSON.parse(String(text));
 }
+function createOauthGrantToken(core, userId, workspaceId) {
+    const redirectUri = 'https://chat.openai.com/aip/callback';
+    const client = core.registerMcpOAuthClient({
+        provider: 'chatgpt',
+        clientName: 'ChatGPT Connector',
+        redirectUris: [redirectUri],
+    });
+    const verifier = randomBytes(32).toString('base64url');
+    const codeChallenge = createHash('sha256').update(verifier).digest('base64url');
+    const issued = core.issueMcpOAuthAuthorizationCode({
+        provider: 'chatgpt',
+        clientId: client.id,
+        userId,
+        workspaceId,
+        scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
+        redirectUri,
+        codeChallenge,
+        codeChallengeMethod: 'S256',
+    });
+    const exchanged = core.exchangeMcpOAuthAuthorizationCode({
+        provider: 'chatgpt',
+        clientId: client.id,
+        code: issued.code,
+        redirectUri,
+        codeVerifier: verifier,
+    });
+    return exchanged.accessToken;
+}
 function seedAnnotatedAttachmentFixture(projectRoot) {
     const core = new TaskforceCore({
         projectRoot,
@@ -323,6 +353,7 @@ describe('Taskforce MCP tool descriptions', () => {
             const getTask = getTool(result, 'get_task');
             const getPaths = getTool(result, 'get_paths');
             const searchImages = getTool(result, 'search_images');
+            const getImage = getTool(result, 'get_image');
             const getDocument = getTool(result, 'get_document');
             const searchDocuments = getTool(result, 'search_documents');
             const listAnnotatedAttachmentSessions = getTool(result, 'get_annotated_attachment_sessions');
@@ -341,10 +372,13 @@ describe('Taskforce MCP tool descriptions', () => {
             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(getImage.description).toContain('placement, or visual correction feedback');
             expect(getDocument.description).toContain('D-123');
             expect(searchDocuments.description).toContain('D-123 reference');
             expect(listAnnotatedAttachmentSessions.description).toContain('saved annotation sessions');
+            expect(listAnnotatedAttachmentSessions.description).toContain('inspect the saved session payload next');
             expect(readAnnotatedAttachmentPayload.description).toContain('derived crop hints');
+            expect(readAnnotatedAttachmentPayload.description).toContain('authoritative instruction source');
             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');
@@ -381,6 +415,14 @@ describe('Taskforce MCP tool descriptions', () => {
             const getTaskAttachments = getTool(result, 'get_task_attachments');
             const readTaskAttachment = getTool(result, 'read_task_attachment');
             const deleteTaskAttachment = getTool(result, 'delete_task_attachment');
+            const getWorkstreamAttachments = getTool(result, 'get_workstream_attachments');
+            const readWorkstreamAttachment = getTool(result, 'read_workstream_attachment');
+            const saveWorkstreamAttachment = getTool(result, 'save_workstream_attachment');
+            const deleteWorkstreamAttachment = getTool(result, 'delete_workstream_attachment');
+            const getInitiativeAttachments = getTool(result, 'get_initiative_attachments');
+            const readInitiativeAttachment = getTool(result, 'read_initiative_attachment');
+            const saveInitiativeAttachment = getTool(result, 'save_initiative_attachment');
+            const deleteInitiativeAttachment = getTool(result, 'delete_initiative_attachment');
             const deleteAnnotatedAttachmentSession = getTool(result, 'delete_annotated_attachment_session');
             const archiveTask = getTool(result, 'archive_task');
             const startTask = getTool(result, 'start_task');
@@ -399,9 +441,14 @@ describe('Taskforce MCP tool descriptions', () => {
             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.inputSchema?.properties?.id).toBeDefined();
+            expect(getImage.inputSchema?.properties?.imageId).toBeDefined();
             expect(getImage.description).toContain('Use this first when the user references an image');
+            expect(getImage.description).toContain('read the saved annotation payload before making changes');
             expect(searchDocuments.description).toContain('get_document');
             expect(searchDocuments.description).toContain('read_document_content');
+            expect(getDocument.inputSchema?.properties?.id).toBeDefined();
+            expect(getDocument.inputSchema?.properties?.documentId).toBeDefined();
             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');
@@ -417,9 +464,24 @@ describe('Taskforce MCP tool descriptions', () => {
             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(getTaskAttachments.inputSchema?.properties?.taskId).toBeDefined();
+            expect(saveTaskAttachment.description).toContain('staged remote uploads');
+            expect(saveTaskAttachment.inputSchema?.properties?.uploadedPath).toBeDefined();
+            expect(saveTaskAttachment.inputSchema?.properties?.uploadDraftId).toBeDefined();
+            expect(saveTaskAttachment.inputSchema?.properties?.mimeType).toBeDefined();
+            expect(saveTaskAttachment.inputSchema?.properties?.sizeBytes).toBeDefined();
+            expect(getTaskAttachments.inputSchema?.properties?.id).toBeDefined();
             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(getWorkstreamAttachments.description).toContain('use read_workstream_attachment for file contents');
+            expect(readWorkstreamAttachment.description).toContain('Prefer this tool over opening attachment path URLs directly');
+            expect(saveWorkstreamAttachment.description).toContain('attach it to a workstream');
+            expect(deleteWorkstreamAttachment.description).toContain('Use get_workstream_attachments first');
+            expect(getInitiativeAttachments.description).toContain('use read_initiative_attachment for file contents');
+            expect(readInitiativeAttachment.description).toContain('Prefer this tool over opening attachment path URLs directly');
+            expect(saveInitiativeAttachment.description).toContain('attach it to an initiative');
+            expect(deleteInitiativeAttachment.description).toContain('Use get_initiative_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');
@@ -428,6 +490,8 @@ describe('Taskforce MCP tool descriptions', () => {
             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(reviewDocument.inputSchema?.properties?.prompt).toBeDefined();
+            expect(reviewDocument.inputSchema?.properties?.comments).toBeDefined();
             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.');
@@ -441,21 +505,25 @@ describe('Taskforce MCP tool descriptions', () => {
             const saveTaskAttachmentSchema = saveTaskAttachment.inputSchema;
             expect(saveTaskAttachmentSchema.properties.content.description).toContain('use this for AI-authored markdown/text attachments');
             expect(saveTaskAttachmentSchema.properties.sourcePath.description).toContain('approved agent workspace root');
+            expect(saveTaskAttachmentSchema.properties.profileToken.description).toContain('does not preserve session identity');
             expect(resolveProfile.description).toContain('AI collaborator profile');
+            expect(resolveProfile.description).toContain('private agent/client state');
+            expect(resolveProfile.description).toContain('Never write profileToken values');
             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');
+            expect(resolveProfile.inputSchema?.properties?.surfaceType?.description).toContain('cli for terminal-native coding agents');
+            expect(resolveProfile.inputSchema?.properties?.surfaceType?.description).toContain('coding_tool for coding surfaces that are not specifically CLI or IDE-native');
+            expect(resolveProfile.inputSchema?.properties?.surfaceType?.description).toContain('If you are unsure or none of those fit');
             const surfaceTypeSchema = resolveProfile.inputSchema?.properties?.surfaceType;
             expect(surfaceTypeSchema?.anyOf?.[0]?.enum).toEqual([
                 'chat_app',
                 'ide',
+                'cli',
                 'coding_tool',
-                'agent',
-                'other'
+                'agent'
             ]);
         }
         finally {
@@ -636,6 +704,32 @@ describe('Taskforce MCP tool descriptions', () => {
             })
         }));
     });
+    it('returns structured transient MCP timeout details for recoverable read failures', async () => {
+        const { buildRecoverableToolErrorResult } = await import('./runtime');
+        const result = buildRecoverableToolErrorResult(new Error('Postgres worker timed out while reading workstream attachments'), 'req-timeout-1');
+        const payload = parseToolJson(result);
+        expect(payload.success).toBe(false);
+        expect(payload.code).toBe('MCP_BACKEND_TIMEOUT');
+        expect(payload.kind).toBe('backend_timeout');
+        expect(payload.retryable).toBe(true);
+        expect(payload.requestId).toBe('req-timeout-1');
+        expect(payload.retryHint).toContain('backend');
+        expect(payload.details).toEqual(expect.objectContaining({
+            kind: 'backend_timeout',
+            retryable: true
+        }));
+    });
+    it('returns structured transient MCP transport details for recoverable transport failures', async () => {
+        const { buildRecoverableToolErrorResult } = await import('./runtime');
+        const result = buildRecoverableToolErrorResult(new Error('fetch failed'), 'req-fetch-1');
+        const payload = parseToolJson(result);
+        expect(payload.success).toBe(false);
+        expect(payload.code).toBe('MCP_TRANSPORT_FAILURE');
+        expect(payload.kind).toBe('transport_failure');
+        expect(payload.retryable).toBe(true);
+        expect(payload.requestId).toBe('req-fetch-1');
+        expect(payload.retryHint).toContain('transport');
+    });
     it('blocks mutating MCP tools until resolve_profile is called', async () => {
         const projectRoot = createProjectRoot();
         try {
@@ -733,7 +827,7 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
-    it('updates and persists metadata when cloud auto-bind reuses an existing exact-match profile', async () => {
+    it('creates a separate cloud profile and persists metadata when a same-name local profile already exists', async () => {
         const projectRoot = createProjectRoot();
         try {
             const initial = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
@@ -754,29 +848,36 @@ describe('Taskforce MCP tool descriptions', () => {
                 authAiProfileSurfaceType: 'coding_tool'
             }));
             expect(currentProfile.profile).toEqual(expect.objectContaining({
-                id: initial.profile.id,
                 name: 'Automation Codex',
                 description: 'OpenAI Codex coding agent connected through MCP.',
                 role: 'Coding Agent',
                 provider: 'OpenAI',
                 model: 'Codex',
-                surfaceType: 'coding_tool'
+                surfaceType: 'coding_tool',
+                seatScope: 'cloud_metered'
             }));
+            expect(currentProfile.profile.id).not.toBe(initial.profile.id);
             const reloadedCore = new TaskforceCore({
                 projectRoot,
                 storagePath: path.join(projectRoot, '.taskforce')
             });
-            expect(reloadedCore.listAiProfiles('workspace-1')).toEqual([
+            expect(reloadedCore.listAiProfiles('workspace-1')).toEqual(expect.arrayContaining([
                 expect.objectContaining({
                     id: initial.profile.id,
                     name: 'Automation Codex',
+                    seatScope: 'local_unmetered'
+                }),
+                expect.objectContaining({
+                    id: currentProfile.profile.id,
+                    name: 'Automation Codex',
                     description: 'OpenAI Codex coding agent connected through MCP.',
                     role: 'Coding Agent',
                     provider: 'OpenAI',
                     model: 'Codex',
-                    surfaceType: 'coding_tool'
+                    surfaceType: 'coding_tool',
+                    seatScope: 'cloud_metered'
                 })
-            ]);
+            ]));
             reloadedCore.close();
         }
         finally {
@@ -801,17 +902,140 @@ describe('Taskforce MCP tool descriptions', () => {
                 id: resolved.profile.id,
                 username: resolved.profile.username
             }));
+            expect(created.createdByActor.meta).not.toHaveProperty('profileToken');
         }
         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 () => {
+    it('persists resolved OAuth connector identity for later stateless writes', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const seedCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            Object.defineProperty(seedCore, 'getAccountAccessStatus', {
+                configurable: true,
+                value: () => ({
+                    gate: 'ok',
+                    hasEntitlement: true,
+                    canAccessApp: true,
+                    canAccessPlans: true,
+                    planSelectionRequired: false,
+                    message: null,
+                    entitlement: null
+                })
+            });
+            const task = seedCore.createTask({ title: 'OAuth connector identity task' }, { workspaceId: 'workspace-1' });
+            const accessToken = createOauthGrantToken(seedCore, 'owner-1', 'workspace-1');
+            const initialAuth = seedCore.authenticateMcpOAuthAccessToken(accessToken);
+            expect(initialAuth?.grantId).toBeTruthy();
+            expect(initialAuth?.aiProfileToken).toBeFalsy();
+            seedCore.close();
+            const resolveRuntime = createRuntime(projectRoot, 'cloud', {
+                authTokenId: initialAuth.grantId,
+            });
+            const resolved = parseToolJson(await callToolWithRuntime(resolveRuntime, 'resolve_profile', {
+                name: 'Codex Connector',
+                icon: 'Code',
+                color: '#0ea5e9',
+            }, { resolveProfile: false }));
+            const authCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            Object.defineProperty(authCore, 'getAccountAccessStatus', {
+                configurable: true,
+                value: () => ({
+                    gate: 'ok',
+                    hasEntitlement: true,
+                    canAccessApp: true,
+                    canAccessPlans: true,
+                    planSelectionRequired: false,
+                    message: null,
+                    entitlement: null
+                })
+            });
+            const persistedAuth = authCore.authenticateMcpOAuthAccessToken(accessToken);
+            expect(persistedAuth).toEqual(expect.objectContaining({
+                grantId: initialAuth.grantId,
+                aiProfileId: resolved.profile.id,
+                aiProfileToken: resolved.profile.profileToken,
+                aiProfileName: 'Codex Connector',
+            }));
+            authCore.close();
+            const writeRuntime = createRuntime(projectRoot, 'cloud', {
+                authTokenId: persistedAuth.grantId,
+                authAiProfileToken: persistedAuth.aiProfileToken || undefined,
+                authAiProfileName: persistedAuth.aiProfileName || undefined,
+            });
+            const result = await callToolWithRuntime(writeRuntime, 'add_comment', {
+                id: task.id,
+                text: 'Stateless connector write after profile resolution',
+            }, { resolveProfile: false });
+            expect(result.isError).toBeFalsy();
+            expect(String(result.content?.[0]?.text || '')).toContain('Comment added');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('allows save_task_attachment in a fresh runtime when profileToken is passed', async () => {
         const projectRoot = createProjectRoot();
         try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({
+                title: 'Stateless attachment token write'
+            }, {
+                workspaceId: 'workspace-1'
+            });
+            core.close();
             const resolved = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
-                name: 'Automation Codex'
+                name: 'Codex',
+                icon: 'Bot',
+                color: '#ef6c00'
             }, { resolveProfile: false }));
+            const result = await callTool(projectRoot, 'local', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'stateless-note.txt',
+                content: 'hello from a stateless attachment write',
+                profileToken: resolved.profile.profileToken,
+            }, { resolveProfile: false });
+            expect(result.isError).not.toBe(true);
+            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 attachment = updated?.attachments?.[0];
+                expect(attachment?.assetId).toMatch(/^asset-/);
+                const store = new WorkspaceAssetStore(after.getDatabaseAdapter(), after.getTenantId());
+                const asset = store.get(String(attachment?.assetId || ''), 'workspace-1');
+                expect(asset?.createdByUserId).toBe(resolved.profile.id);
+            }
+            finally {
+                after.close();
+            }
+        }
+        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, 'cloud', 'resolve_profile', {
+                name: 'Automation Codex'
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false
+            }));
             const created = parseToolJson(await callTool(projectRoot, 'cloud', 'create_task', {
                 title: 'Configured token write'
             }, {
@@ -866,6 +1090,100 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('blocks cloud auto-bind when the configured AI profile has been retired by name until resolve_profile explicitly reactivates it', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const resolved = core.resolveAiProfile({
+                workspaceId: 'workspace-1',
+                name: 'Automation Codex',
+            }, { trustedSeatScope: 'cloud_metered' });
+            core.archiveAiProfile({
+                workspaceId: 'workspace-1',
+                profileId: resolved.profile.id,
+                archivedBy: 'owner-1',
+                reason: 'manual_archive'
+            });
+            core.close();
+            const blocked = await callTool(projectRoot, 'cloud', 'create_task', {
+                title: 'Should stay retired'
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileName: 'Automation Codex'
+            });
+            expect(blocked.isError).toBe(true);
+            const blockedPayload = parseToolJson(blocked);
+            expect(blockedPayload.code).toBe('AI_PROFILE_RETIRED');
+            expect(blockedPayload.error).toContain('has been retired from this workspace');
+            expect(blockedPayload.nextTool).toBe('resolve_profile');
+            const reactivated = parseToolJson(await callTool(projectRoot, 'cloud', 'resolve_profile', {
+                name: 'Automation Codex',
+                surfaceType: 'agent'
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileName: 'Automation Codex'
+            }));
+            expect(reactivated.created).toBe(false);
+            expect(reactivated.profile.id).toBe(resolved.profile.id);
+            expect(reactivated.profile.archivedAt ?? null).toBeNull();
+            const created = parseToolJson(await callTool(projectRoot, 'cloud', 'create_task', {
+                title: 'Reactivated automation write'
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileName: 'Automation Codex'
+            }));
+            expect(created.title).toBe('Reactivated automation write');
+            expect(created.createdBy).toBe(resolved.profile.id);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('blocks cloud auto-bind when the configured AI profile token belongs to a retired profile', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const resolved = core.resolveAiProfile({
+                workspaceId: 'workspace-1',
+                name: 'Automation Codex',
+            }, { trustedSeatScope: 'cloud_metered' });
+            core.archiveAiProfile({
+                workspaceId: 'workspace-1',
+                profileId: resolved.profile.id,
+                archivedBy: 'owner-1',
+                reason: 'manual_archive'
+            });
+            core.close();
+            const blocked = await callTool(projectRoot, 'cloud', 'create_task', {
+                title: 'Token should stay retired'
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileToken: resolved.profile.profileToken,
+                authAiProfileName: 'Automation Codex'
+            });
+            expect(blocked.isError).toBe(true);
+            const blockedPayload = parseToolJson(blocked);
+            expect(blockedPayload.code).toBe('AI_PROFILE_RETIRED');
+            expect(blockedPayload.details).toEqual(expect.objectContaining({
+                profileId: resolved.profile.id,
+                profileToken: resolved.profile.profileToken,
+                archivedReason: 'manual_archive'
+            }));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
     it('blocks cloud auto-bind when the workspace has no remaining ai profile seats', async () => {
         const projectRoot = createProjectRoot();
         try {
@@ -895,8 +1213,8 @@ describe('Taskforce MCP tool descriptions', () => {
             });
             core.resolveAiProfile({
                 workspaceId: 'workspace-1',
-                name: 'Existing Automation Bot'
-            });
+                name: 'Existing Automation Bot',
+            }, { trustedSeatScope: 'cloud_metered' });
             core.close();
             const result = await callTool(projectRoot, 'cloud', 'create_task', {
                 title: 'Blocked automation write'
@@ -1009,8 +1327,8 @@ describe('Taskforce MCP tool descriptions', () => {
             });
             core.resolveAiProfile({
                 workspaceId: 'workspace-1',
-                name: 'Existing Automation Bot'
-            });
+                name: 'Existing Automation Bot',
+            }, { trustedSeatScope: 'cloud_metered' });
             core.close();
             const result = await callTool(projectRoot, 'cloud', 'create_task', {
                 title: 'Recovered per-call token write',
@@ -1035,112 +1353,435 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
-    it('claims unassigned tasks and marks them in progress through start_task', async () => {
+    it('keeps local MCP profile resolution unmetered even when cloud seats are full', 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.upsertPlanCatalog({ planId: 'free', displayName: 'Free', status: 'active' });
+            core.ensureBootstrapUserAccess({
+                userId: 'owner-u1',
+                workspaceId: 'workspace-1',
+                role: 'owner',
+                email: 'owner@example.com'
+            });
+            core.updatePlanVersionFeatures({
+                planVersionId: 'free-v1',
+                features: [
+                    { featureKey: 'collaboration.ai_profiles', access: 'limited', config: { maxAiProfiles: 1 } }
+                ]
+            });
+            core.updateAccountEntitlement({
+                accountId: 'owner-u1',
+                planVersionId: 'free-v1',
+                entitlementState: 'active',
+                actorUserId: 'system-admin',
+                actorRole: 'system_admin'
+            });
+            core.resolveAiProfile({
+                workspaceId: 'workspace-1',
+                name: 'Existing Automation Bot',
+            }, { trustedSeatScope: 'cloud_metered' });
             core.close();
-            const result = parseToolJson(await callTool(projectRoot, 'local', 'start_task', {
-                id: seeded.referenceLabel
+            const payload = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
+                name: 'Local Codex'
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false
             }));
-            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-/);
+            expect(payload.created).toBe(true);
+            expect(payload.profile.name).toBe('Local Codex');
+            expect(payload.profile.seatScope).toBe('local_unmetered');
         }
         finally {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
-    it('sets tasks already assigned to the current AI in progress without stealing ownership', async () => {
+    it('derives profile seat scope from the MCP runtime instead of auth metadata', async () => {
         const projectRoot = createProjectRoot();
         try {
-            const profile = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
+            const localRuntime = createTaskforceMcpServer({
+                projectRoot,
+                runtimeMode: 'local',
+                workspaceId: 'workspace-1',
+                logStartup: false,
+                auth: {
+                    aiProfileSeatScope: 'cloud_metered',
+                    aiProfileName: 'Codex',
+                    aiProfileRole: 'Implementation',
+                    aiProfileProvider: 'OpenAI',
+                    aiProfileModel: 'gpt-5',
+                    aiProfileSurfaceType: 'coding_tool',
+                }
+            });
+            const localPayload = parseToolJson(await callToolWithRuntime(localRuntime, 'resolve_profile', {
                 name: 'Codex',
-                icon: 'Bot',
-                color: '#ef6c00'
+                surfaceType: 'coding_tool',
+            }, {
+                resolveProfile: false
             }));
-            const core = new TaskforceCore({
+            expect(localPayload.profile.seatScope).toBe('local_unmetered');
+            const cloudRuntime = createTaskforceMcpServer({
                 projectRoot,
-                storagePath: path.join(projectRoot, '.taskforce')
+                runtimeMode: 'cloud',
+                workspaceId: 'workspace-1',
+                logStartup: false,
+                auth: {
+                    scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
+                    userId: 'owner-1',
+                    actorType: 'oauth',
+                    aiProfileSeatScope: 'local_unmetered',
+                    aiProfileName: 'Cloud Codex',
+                    aiProfileSurfaceType: 'coding_tool',
+                }
             });
-            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
+            const cloudPayload = parseToolJson(await callToolWithRuntime(cloudRuntime, 'resolve_profile', {
+                name: 'Cloud Codex',
+                surfaceType: 'coding_tool',
+            }, {
+                resolveProfile: false
             }));
-            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');
+            expect(cloudPayload.profile.seatScope).toBe('cloud_metered');
         }
         finally {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
-    it('refuses to steal tasks already assigned to someone else through start_task', async () => {
+    it('creates a separate local MCP profile when a cloud profile with the same name already exists', 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' });
+            const cloud = core.resolveAiProfile({
+                workspaceId: 'workspace-1',
+                name: 'Codex',
+                surfaceType: 'coding_tool'
+            }, { trustedSeatScope: 'cloud_metered' });
             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');
+            const payload = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
+                name: 'Codex',
+                surfaceType: 'coding_tool'
+            }, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false
+            }));
+            expect(payload.created).toBe(true);
+            expect(payload.profile.id).not.toBe(cloud.profile.id);
+            expect(payload.profile.seatScope).toBe('local_unmetered');
         }
         finally {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
-    it('rejects terminal tasks through start_task', async () => {
+    it('attributes system-authored MCP comments to the current AI profile', async () => {
         const projectRoot = createProjectRoot();
         try {
-            const core = new TaskforceCore({
+            const runtime = createTaskforceMcpServer({
                 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
+                runtimeMode: 'local',
+                workspaceId: 'workspace-1',
+                logStartup: false,
             });
-            expect(result.isError).toBe(true);
-            expect(result.content?.[0]?.text).toContain('must be reopened explicitly');
-        }
-        finally {
-            fs.rmSync(projectRoot, { recursive: true, force: true });
-        }
-    });
+            const profilePayload = parseToolJson(await callToolWithRuntime(runtime, 'resolve_profile', {
+                name: 'Codex',
+                icon: 'Bot',
+                surfaceType: 'coding_tool',
+            }, {
+                resolveProfile: false,
+            }));
+            const created = parseToolJson(await callToolWithRuntime(runtime, 'create_task', {
+                title: 'Comment attribution task',
+            }));
+            await callToolWithRuntime(runtime, 'add_comment', {
+                id: created.referenceLabel,
+                text: 'Completed the work.',
+                author: 'system',
+            });
+            const task = parseToolJson(await callToolWithRuntime(runtime, 'get_task', {
+                id: created.referenceLabel,
+            }));
+            const comment = task.comments.find((entry) => entry.text === 'Completed the work.');
+            const event = task.taskEvents.find((entry) => entry.details?.commentId === comment?.id);
+            expect(comment.author).toBe(profilePayload.profile.id);
+            expect(comment.submittedAuthor).toBe(profilePayload.profile.id);
+            expect(comment.actor.label).toBe('Codex');
+            expect(event.actor).toBe(profilePayload.profile.id);
+            expect(event.actorType).toBe('ai');
+            expect(event.actorProfile.label).toBe('Codex');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('canonicalizes ambiguous AI display-name comment authors back to the bound profile', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const seedCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            seedCore.resolveAiProfile({ workspaceId: 'workspace-1', name: 'Codex', surfaceType: 'coding_tool' }, { trustedSeatScope: 'cloud_metered' });
+            seedCore.close();
+            const runtime = createTaskforceMcpServer({
+                projectRoot,
+                runtimeMode: 'local',
+                workspaceId: 'workspace-1',
+                logStartup: false,
+            });
+            const profilePayload = parseToolJson(await callToolWithRuntime(runtime, 'resolve_profile', {
+                name: 'Codex',
+                icon: 'Bot',
+                surfaceType: 'coding_tool',
+            }, {
+                resolveProfile: false,
+            }));
+            const created = parseToolJson(await callToolWithRuntime(runtime, 'create_task', {
+                title: 'Ambiguous comment attribution task',
+            }));
+            await callToolWithRuntime(runtime, 'add_comment', {
+                id: created.referenceLabel,
+                text: 'Bound actor should win.',
+                author: 'Codex',
+            });
+            const task = parseToolJson(await callToolWithRuntime(runtime, 'get_task', {
+                id: created.referenceLabel,
+            }));
+            const comment = task.comments.find((entry) => entry.text === 'Bound actor should win.');
+            const event = task.taskEvents.find((entry) => entry.details?.commentId === comment?.id);
+            expect(comment.author).toBe(profilePayload.profile.id);
+            expect(comment.submittedAuthor).toBe(profilePayload.profile.id);
+            expect(comment.actor.id).toBe(profilePayload.profile.id);
+            expect(event.actor).toBe(profilePayload.profile.id);
+            expect(event.actorType).toBe('ai');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('preserves explicit human comment overrides for MCP writes', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const runtime = createTaskforceMcpServer({
+                projectRoot,
+                runtimeMode: 'local',
+                workspaceId: 'workspace-1',
+                logStartup: false,
+            });
+            const created = parseToolJson(await callToolWithRuntime(runtime, 'create_task', {
+                title: 'Human comment override task',
+            }));
+            await callToolWithRuntime(runtime, 'add_comment', {
+                id: created.referenceLabel,
+                text: 'Human-authored note.',
+                author: 'user',
+            });
+            const task = parseToolJson(await callToolWithRuntime(runtime, 'get_task', {
+                id: created.referenceLabel,
+            }));
+            const comment = task.comments.find((entry) => entry.text === 'Human-authored note.');
+            const event = task.taskEvents.find((entry) => entry.details?.commentId === comment?.id);
+            expect(comment.author).toBe('user');
+            expect(comment.submittedAuthor).toBe('user');
+            expect(comment.actor.id).toBe('user');
+            expect(event.actor).toBe('user');
+            expect(event.actorType).toBe('human');
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('ignores mutable MCP comment author aliases when an AI profile is bound', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const runtime = createTaskforceMcpServer({
+                projectRoot,
+                runtimeMode: 'local',
+                workspaceId: 'workspace-1',
+                logStartup: false,
+            });
+            const profilePayload = parseToolJson(await callToolWithRuntime(runtime, 'resolve_profile', {
+                name: 'Codex',
+                icon: 'Bot',
+                surfaceType: 'coding_tool',
+            }, {
+                resolveProfile: false,
+            }));
+            const created = parseToolJson(await callToolWithRuntime(runtime, 'create_task', {
+                title: 'Strict comment attribution task',
+            }));
+            await callToolWithRuntime(runtime, 'add_comment', {
+                id: created.referenceLabel,
+                text: 'Alias should not win over the bound profile.',
+                author: 'Claude',
+            });
+            await callToolWithRuntime(runtime, 'add_comment', {
+                id: created.referenceLabel,
+                text: 'Explicit human override stays human.',
+                author: 'user',
+            });
+            const task = parseToolJson(await callToolWithRuntime(runtime, 'get_task', {
+                id: created.referenceLabel,
+            }));
+            const aliasComment = task.comments.find((entry) => entry.text === 'Alias should not win over the bound profile.');
+            const humanComment = task.comments.find((entry) => entry.text === 'Explicit human override stays human.');
+            expect(aliasComment.author).toBe(profilePayload.profile.id);
+            expect(aliasComment.submittedAuthor).toBe(profilePayload.profile.id);
+            expect(aliasComment.actor.label).toBe('Codex');
+            expect(humanComment.author).toBe('user');
+            expect(humanComment.submittedAuthor).toBe('user');
+            expect(humanComment.actor.kind).toBe('human');
+        }
+        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('allows review tasks to resume 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 review resume',
+                status: 'review',
+                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.previousStatus).toBe('review');
+            expect(result.task.status).toBe('in-progress');
+            expect(result.task.assignee).toMatch(/^ai-profile-/);
+        }
+        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 done and cancelled tasks through start_task', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const doneTask = core.createTask({
+                title: 'Start helper done refusal',
+                status: 'done',
+                assignee: 'unassigned'
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            const cancelledTask = core.createTask({
+                title: 'Start helper cancelled refusal',
+                status: 'cancelled',
+                assignee: 'unassigned'
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            core.close();
+            const doneResult = await callTool(projectRoot, 'local', 'start_task', {
+                id: doneTask.referenceLabel
+            });
+            const cancelledResult = await callTool(projectRoot, 'local', 'start_task', {
+                id: cancelledTask.referenceLabel
+            });
+            expect(doneResult.isError).toBe(true);
+            expect(doneResult.content?.[0]?.text).toContain('must be reopened explicitly');
+            expect(cancelledResult.isError).toBe(true);
+            expect(cancelledResult.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 {
@@ -1372,6 +2013,7 @@ describe('Taskforce MCP tool descriptions', () => {
                     isCurrentProfile: true
                 })
             ]));
+            expect(JSON.stringify(payload.assignees)).not.toContain(resolved.profile.profileToken);
         }
         finally {
             fs.rmSync(projectRoot, { recursive: true, force: true });
@@ -1483,6 +2125,50 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('auto-binds a configured cloud AI name to an existing profile when the token is stale', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const seedCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const existing = seedCore.resolveAiProfile({
+                workspaceId: 'workspace-1',
+                name: 'Felix Leiter',
+                provider: 'OpenAI',
+                model: 'openai-codex/gpt-5.4',
+                surfaceType: 'agent',
+            }, { trustedSeatScope: 'cloud_metered' });
+            seedCore.close();
+            const payload = parseToolJson(await callTool(projectRoot, 'cloud', 'get_current_profile', {}, {
+                workspaceId: 'workspace-1',
+                resolveProfile: false,
+                authAiProfileToken: 'tfp_stale_felix_leiter_token',
+                authAiProfileName: 'Felix Leiter',
+                authAiProfileProvider: 'OpenClaw',
+                authAiProfileModel: 'gpt-5.4',
+                authAiProfileSurfaceType: 'agent'
+            }));
+            expect(payload.identityBound).toBe(true);
+            expect(payload.bindingSource).toBe('connection_bootstrap');
+            expect(payload.profile).toEqual(expect.objectContaining({
+                id: existing.profile.id,
+                name: 'Felix Leiter',
+                provider: 'OpenClaw',
+                model: 'gpt-5.4',
+                seatScope: 'cloud_metered',
+            }));
+            const verifyCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            expect(verifyCore.listAiProfiles('workspace-1')).toHaveLength(1);
+            verifyCore.close();
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
     it('searches tasks by T-XXX reference label via reference_number', async () => {
         const projectRoot = createProjectRoot();
         try {
@@ -1603,68 +2289,274 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
-    it('manages planning entities, relationships, and structured checklist tools', async () => {
+    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('keeps the MCP runtime usable after linking a task to a workstream', async () => {
+        const projectRoot = createProjectRoot();
+        const runtime = createRuntime(projectRoot, 'local');
+        try {
+            const createdWorkstream = parseToolJson(await callToolWithRuntime(runtime, 'create_workstream', {
+                title: 'Transport-safe workstream'
+            }));
+            const createdTask = parseToolJson(await callToolWithRuntime(runtime, 'create_task', {
+                title: 'Transport-safe task'
+            }));
+            const taskLinked = parseToolJson(await callToolWithRuntime(runtime, 'set_task_workstream', {
+                taskId: createdTask.referenceLabel,
+                workstreamId: createdWorkstream.workstream.referenceLabel
+            }));
+            expect(taskLinked.workstreamId).toBe(createdWorkstream.workstream.id);
+            const workstreamRead = parseToolJson(await callToolWithRuntime(runtime, 'get_workstream', {
+                id: createdWorkstream.workstream.referenceLabel
+            }));
+            expect(workstreamRead.workstream.id).toBe(createdWorkstream.workstream.id);
+            expect(workstreamRead.tasks).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    id: createdTask.id,
+                    workstreamId: createdWorkstream.workstream.id
+                })
+            ]));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('retries transient planning read failures before returning get_workstream results', async () => {
+        const projectRoot = createProjectRoot();
+        const runtime = createRuntime(projectRoot, 'cloud');
+        try {
+            const workstream = runtime.core.createWorkstream({ title: 'Retryable read workstream' }, 'workspace-1');
+            const originalListWorkstreams = runtime.core.listWorkstreams.bind(runtime.core);
+            let attempts = 0;
+            const listWorkstreamsSpy = vi.spyOn(runtime.core, 'listWorkstreams').mockImplementation((workspaceId) => {
+                attempts += 1;
+                if (attempts === 1) {
+                    throw new Error('Postgres worker timed out while reading workstreams');
+                }
+                return originalListWorkstreams(workspaceId);
+            });
+            const workstreamRead = parseToolJson(await callToolWithRuntime(runtime, 'get_workstream', {
+                id: workstream.referenceLabel
+            }));
+            expect(attempts).toBe(2);
+            expect(workstreamRead.workstream.id).toBe(workstream.id);
+            listWorkstreamsSpy.mockRestore();
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('returns the created workstream when post-write workstream hydration times out', async () => {
+        const projectRoot = createProjectRoot();
+        const originalGetWorkstream = TaskforceCore.prototype.getWorkstream;
+        let injected = false;
+        const getWorkstreamSpy = vi.spyOn(TaskforceCore.prototype, 'getWorkstream').mockImplementation(function (id, workspaceId) {
+            const result = originalGetWorkstream.call(this, id, workspaceId);
+            if (!injected && result?.title === 'Hydration fallback workstream') {
+                injected = true;
+                throw new Error('Postgres worker timed out while reading workstreams');
+            }
+            return result;
+        });
+        try {
+            const created = parseToolJson(await callTool(projectRoot, 'local', 'create_workstream', {
+                title: 'Hydration fallback workstream'
+            }));
+            expect(created.workstream.referenceLabel).toMatch(/^WS-/);
+            expect(created.workstream.title).toBe('Hydration fallback workstream');
+        }
+        finally {
+            getWorkstreamSpy.mockRestore();
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('returns the created workstream when post-write response hydration times out', async () => {
+        const projectRoot = createProjectRoot();
+        const originalListTasks = TaskforceCore.prototype.listTasks;
+        let injected = false;
+        const listTasksSpy = vi.spyOn(TaskforceCore.prototype, 'listTasks').mockImplementation(function (workspaceId) {
+            if (!injected) {
+                injected = true;
+                throw new Error('Postgres worker timed out while hydrating workstream response');
+            }
+            return originalListTasks.call(this, workspaceId);
+        });
+        try {
+            const created = parseToolJson(await callTool(projectRoot, 'local', 'create_workstream', {
+                title: 'Response hydration fallback workstream'
+            }));
+            expect(created.workstream.referenceLabel).toMatch(/^WS-/);
+            expect(created.workstream.title).toBe('Response hydration fallback workstream');
+            expect(created.responseHydration).toEqual(expect.objectContaining({
+                fallback: true,
+                code: 'MCP_BACKEND_TIMEOUT',
+                nextTool: 'get_workstream'
+            }));
+        }
+        finally {
+            listTasksSpy.mockRestore();
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('retries transient get_initiative read failures before returning results', async () => {
+        const projectRoot = createProjectRoot();
+        const runtime = createRuntime(projectRoot, 'cloud');
+        try {
+            const initiative = runtime.core.createInitiative({ title: 'Retryable initiative read' }, 'workspace-1');
+            const originalListInitiatives = runtime.core.listInitiatives.bind(runtime.core);
+            let attempts = 0;
+            const listInitiativesSpy = vi.spyOn(runtime.core, 'listInitiatives').mockImplementation((workspaceId) => {
+                attempts += 1;
+                if (attempts === 1) {
+                    throw new Error('Postgres worker timed out while reading initiatives');
+                }
+                return originalListInitiatives(workspaceId);
+            });
+            const initiativeRead = parseToolJson(await callToolWithRuntime(runtime, 'get_initiative', {
+                id: initiative.referenceLabel
+            }));
+            expect(attempts).toBe(2);
+            expect(initiativeRead.initiative.id).toBe(initiative.id);
+            listInitiativesSpy.mockRestore();
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('keeps save_initiative_attachment successful when post-write initiative hydration times out', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const createdInitiative = parseToolJson(await callTool(projectRoot, 'local', 'create_initiative', {
+                title: 'Hydration fallback initiative'
+            }));
+            const originalGetInitiative = TaskforceCore.prototype.getInitiative;
+            let injected = false;
+            const getInitiativeSpy = vi.spyOn(TaskforceCore.prototype, 'getInitiative').mockImplementation(function (id, workspaceId) {
+                const result = originalGetInitiative.call(this, id, workspaceId);
+                if (!injected
+                    && result
+                    && result.id === createdInitiative.initiative.id
+                    && Array.isArray(result.attachments)
+                    && result.attachments.some((item) => item && typeof item === 'object' && item.displayName === 'hydration-note.md')) {
+                    injected = true;
+                    throw new Error('Postgres worker timed out while reading initiatives');
+                }
+                return result;
+            });
+            try {
+                const saveResult = await callTool(projectRoot, 'local', 'save_initiative_attachment', {
+                    id: createdInitiative.initiative.referenceLabel,
+                    filename: 'hydration-note.md',
+                    content: '# Hydration fallback\n'
+                });
+                expect(String(saveResult.content?.[0]?.text || '')).toContain('Initiative attachment saved and attached');
+            }
+            finally {
+                getInitiativeSpy.mockRestore();
+            }
+            const attachments = parseToolJson(await callTool(projectRoot, 'local', 'get_initiative_attachments', {
+                id: createdInitiative.initiative.referenceLabel
+            }));
+            expect(attachments.attachments).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    displayName: 'hydration-note.md'
+                })
+            ]));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('returns the archived workstream when the post-archive refresh times out', 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
+            const created = parseToolJson(await callTool(projectRoot, 'local', 'create_workstream', {
+                title: 'Archivable hydration fallback workstream'
             }));
-            expect(taskCleared.workstreamId).toBeNull();
+            const originalGetWorkstream = TaskforceCore.prototype.getWorkstream;
+            let injected = false;
+            const getWorkstreamSpy = vi.spyOn(TaskforceCore.prototype, 'getWorkstream').mockImplementation(function (id, workspaceId) {
+                const result = originalGetWorkstream.call(this, id, workspaceId);
+                if (!injected && result && result.id === created.workstream.id && result.isArchived === true) {
+                    injected = true;
+                    throw new Error('Postgres worker timed out while reading workstreams');
+                }
+                return result;
+            });
+            try {
+                const archived = parseToolJson(await callTool(projectRoot, 'local', 'archive_workstream', {
+                    id: created.workstream.referenceLabel
+                }));
+                expect(archived.workstream.isArchived).toBe(true);
+            }
+            finally {
+                getWorkstreamSpy.mockRestore();
+            }
         }
         finally {
             fs.rmSync(projectRoot, { recursive: true, force: true });
@@ -1999,6 +2891,222 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('supports staged remote image uploads for save_task_attachment in cloud runtime', async () => {
+        const projectRoot = createProjectRoot();
+        const previousEnv = {
+            provider: process.env.TASKFORCE_OBJECT_STORAGE_PROVIDER,
+            accountId: process.env.R2_ACCOUNT_ID,
+            bucket: process.env.R2_BUCKET,
+            accessKeyId: process.env.R2_ACCESS_KEY_ID,
+            secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+            endpoint: process.env.R2_ENDPOINT,
+            uploadTtl: process.env.R2_SIGNED_UPLOAD_TTL_SECONDS,
+        };
+        try {
+            process.env.TASKFORCE_OBJECT_STORAGE_PROVIDER = 'r2';
+            process.env.R2_ACCOUNT_ID = 'acct-1';
+            process.env.R2_BUCKET = 'taskforce-test';
+            process.env.R2_ACCESS_KEY_ID = 'access-key';
+            process.env.R2_SECRET_ACCESS_KEY = 'secret-key';
+            process.env.R2_ENDPOINT = 'https://example.r2.invalid';
+            process.env.R2_SIGNED_UPLOAD_TTL_SECONDS = '600';
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Cloud staged image attachment test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const fetchMock = vi.fn(async (input, init) => {
+                const method = String(init?.method || 'GET').toUpperCase();
+                if (method === 'GET') {
+                    return new Response(Buffer.from([0x89, 0x50, 0x4e, 0x47]), {
+                        status: 200,
+                        headers: { 'content-type': 'image/png' }
+                    });
+                }
+                return new Response('', { status: 200 });
+            });
+            vi.stubGlobal('fetch', fetchMock);
+            const staged = parseToolJson(await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'proof.png',
+                mimeType: 'image/png',
+                sizeBytes: 4
+            }));
+            expect(staged.mode).toBe('staged_upload');
+            expect(staged.status).toBe('upload_required');
+            expect(staged.filename).toBe('proof.png');
+            expect(staged.upload.method).toBe('PUT');
+            expect(staged.upload.headers['Content-Type']).toBe('image/png');
+            expect(staged.upload.uploadUrl).toContain('X-Amz-Signature=');
+            expect(staged.upload.uploadedPath).toContain('workspaces/workspace-1/assets/images/');
+            expect(staged.uploadDraftId).toContain('task-attachment-draft-');
+            expect(staged.finalize.tool).toBe('save_task_attachment');
+            expect(staged.finalize.arguments.uploadDraftId).toBe(staged.uploadDraftId);
+            expect(staged.finalize.arguments.uploadedPath).toBe(staged.upload.uploadedPath);
+            await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'proof.png',
+                mimeType: 'image/png',
+                uploadDraftId: staged.uploadDraftId,
+                uploadedPath: staged.upload.uploadedPath
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', { id: task.referenceLabel }));
+            expect(listed.attachments).toHaveLength(1);
+            expect(listed.attachments[0]).toMatchObject({
+                kind: 'image',
+                mimeType: 'image/png',
+                originalFilename: 'proof.png',
+                readableAsText: false,
+            });
+            const verifyCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const updated = verifyCore.getTask(task.id, 'workspace-1');
+                const store = new WorkspaceAssetStore(verifyCore.getDatabaseAdapter(), verifyCore.getTenantId());
+                const asset = store.get(String(listed.attachments[0]?.assetId || ''), 'workspace-1');
+                expect(updated?.attachments).toHaveLength(1);
+                expect(updated?.attachments?.[0]).toMatchObject({
+                    path: expect.stringMatching(/^\/api\/taskforce\/context\//),
+                    originalFilename: 'proof.png',
+                });
+                expect(asset).toEqual(expect.objectContaining({
+                    kind: 'image',
+                    mimeType: 'image/png',
+                    storageProvider: 'r2',
+                    storageKey: staged.upload.uploadedPath,
+                }));
+            }
+            finally {
+                verifyCore.close();
+            }
+        }
+        finally {
+            vi.unstubAllGlobals();
+            if (previousEnv.provider === undefined)
+                delete process.env.TASKFORCE_OBJECT_STORAGE_PROVIDER;
+            else
+                process.env.TASKFORCE_OBJECT_STORAGE_PROVIDER = previousEnv.provider;
+            if (previousEnv.accountId === undefined)
+                delete process.env.R2_ACCOUNT_ID;
+            else
+                process.env.R2_ACCOUNT_ID = previousEnv.accountId;
+            if (previousEnv.bucket === undefined)
+                delete process.env.R2_BUCKET;
+            else
+                process.env.R2_BUCKET = previousEnv.bucket;
+            if (previousEnv.accessKeyId === undefined)
+                delete process.env.R2_ACCESS_KEY_ID;
+            else
+                process.env.R2_ACCESS_KEY_ID = previousEnv.accessKeyId;
+            if (previousEnv.secretAccessKey === undefined)
+                delete process.env.R2_SECRET_ACCESS_KEY;
+            else
+                process.env.R2_SECRET_ACCESS_KEY = previousEnv.secretAccessKey;
+            if (previousEnv.endpoint === undefined)
+                delete process.env.R2_ENDPOINT;
+            else
+                process.env.R2_ENDPOINT = previousEnv.endpoint;
+            if (previousEnv.uploadTtl === undefined)
+                delete process.env.R2_SIGNED_UPLOAD_TTL_SECONDS;
+            else
+                process.env.R2_SIGNED_UPLOAD_TTL_SECONDS = previousEnv.uploadTtl;
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('rejects forged staged upload finalization for save_task_attachment in cloud runtime', async () => {
+        const projectRoot = createProjectRoot();
+        const previousEnv = {
+            provider: process.env.TASKFORCE_OBJECT_STORAGE_PROVIDER,
+            accountId: process.env.R2_ACCOUNT_ID,
+            bucket: process.env.R2_BUCKET,
+            accessKeyId: process.env.R2_ACCESS_KEY_ID,
+            secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+            endpoint: process.env.R2_ENDPOINT,
+            uploadTtl: process.env.R2_SIGNED_UPLOAD_TTL_SECONDS,
+        };
+        try {
+            process.env.TASKFORCE_OBJECT_STORAGE_PROVIDER = 'r2';
+            process.env.R2_ACCOUNT_ID = 'acct-1';
+            process.env.R2_BUCKET = 'taskforce-test';
+            process.env.R2_ACCESS_KEY_ID = 'access-key';
+            process.env.R2_SECRET_ACCESS_KEY = 'secret-key';
+            process.env.R2_ENDPOINT = 'https://example.r2.invalid';
+            process.env.R2_SIGNED_UPLOAD_TTL_SECONDS = '600';
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Cloud staged image attachment reject test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const fetchMock = vi.fn(async (input, init) => {
+                const method = String(init?.method || 'GET').toUpperCase();
+                if (method === 'GET') {
+                    return new Response(Buffer.from([0x89, 0x50, 0x4e, 0x47]), {
+                        status: 200,
+                        headers: { 'content-type': 'image/png' }
+                    });
+                }
+                return new Response('', { status: 200 });
+            });
+            vi.stubGlobal('fetch', fetchMock);
+            const staged = parseToolJson(await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'proof.png',
+                mimeType: 'image/png',
+                sizeBytes: 4
+            }));
+            const bareResult = await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'proof.png',
+                mimeType: 'image/png',
+                uploadedPath: staged.upload.uploadedPath
+            });
+            expect(bareResult.content?.[0]?.text).toContain('uploadedPath finalization requires uploadDraftId');
+            const forgedResult = await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.referenceLabel,
+                filename: 'proof.png',
+                mimeType: 'image/png',
+                uploadDraftId: staged.uploadDraftId,
+                uploadedPath: 'workspaces/workspace-1/assets/images/asset-deadbeefdeadbeefdeadbeefdeadbeef-proof.png'
+            });
+            expect(forgedResult.content?.[0]?.text).toContain('uploadedPath does not match the staged upload draft');
+        }
+        finally {
+            vi.unstubAllGlobals();
+            if (previousEnv.provider === undefined)
+                delete process.env.TASKFORCE_OBJECT_STORAGE_PROVIDER;
+            else
+                process.env.TASKFORCE_OBJECT_STORAGE_PROVIDER = previousEnv.provider;
+            if (previousEnv.accountId === undefined)
+                delete process.env.R2_ACCOUNT_ID;
+            else
+                process.env.R2_ACCOUNT_ID = previousEnv.accountId;
+            if (previousEnv.bucket === undefined)
+                delete process.env.R2_BUCKET;
+            else
+                process.env.R2_BUCKET = previousEnv.bucket;
+            if (previousEnv.accessKeyId === undefined)
+                delete process.env.R2_ACCESS_KEY_ID;
+            else
+                process.env.R2_ACCESS_KEY_ID = previousEnv.accessKeyId;
+            if (previousEnv.secretAccessKey === undefined)
+                delete process.env.R2_SECRET_ACCESS_KEY;
+            else
+                process.env.R2_SECRET_ACCESS_KEY = previousEnv.secretAccessKey;
+            if (previousEnv.endpoint === undefined)
+                delete process.env.R2_ENDPOINT;
+            else
+                process.env.R2_ENDPOINT = previousEnv.endpoint;
+            if (previousEnv.uploadTtl === undefined)
+                delete process.env.R2_SIGNED_UPLOAD_TTL_SECONDS;
+            else
+                process.env.R2_SIGNED_UPLOAD_TTL_SECONDS = previousEnv.uploadTtl;
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
     it('allows generic markdown review attachments without requiring the legacy review template', async () => {
         const projectRoot = createProjectRoot();
         try {
@@ -2608,6 +3716,146 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('saves, lists, and reads workstream attachments by workstream reference', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const workstream = core.createWorkstream({ title: 'Attachment workstream' }, 'workspace-1');
+            core.close();
+            await callTool(projectRoot, 'cloud', 'save_workstream_attachment', {
+                id: workstream.referenceLabel,
+                filename: 'findings.md',
+                content: '# Findings\nWorkstream-specific notes',
+                caption: 'Security findings'
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'cloud', 'get_workstream_attachments', { id: workstream.referenceLabel }));
+            const readBack = parseToolJson(await callTool(projectRoot, 'cloud', 'read_workstream_attachment', {
+                workstreamId: workstream.referenceLabel,
+                attachmentId: listed.attachments[0]?.attachmentId
+            }));
+            const workstreamPayload = parseToolJson(await callTool(projectRoot, 'cloud', 'get_workstream', { id: workstream.referenceLabel }));
+            const taskToolResult = await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: workstream.referenceLabel,
+                filename: 'wrong-tool.md',
+                content: '# Wrong tool'
+            });
+            const verifyCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const store = new WorkspaceAssetStore(verifyCore.getDatabaseAdapter(), verifyCore.getTenantId());
+                const links = store.listLinksForAsset(String(listed.attachments[0]?.assetId || ''), 'workspace-1');
+                expect(listed.workstreamId).toBe(workstream.id);
+                expect(listed.referenceLabel).toBe(workstream.referenceLabel);
+                expect(listed.attachments).toHaveLength(1);
+                expect(listed.attachments[0]?.kind).toBe('document');
+                expect(listed.attachments[0]?.readableAsText).toBe(true);
+                expect(readBack.workstreamId).toBe(workstream.id);
+                expect(readBack.content).toContain('Workstream-specific notes');
+                expect(workstreamPayload.workstream.attachments).toHaveLength(1);
+                expect(workstreamPayload.workstream.attachments[0]).toMatchObject({
+                    assetId: listed.attachments[0]?.assetId,
+                    referenceLabel: listed.attachments[0]?.referenceLabel,
+                    originalFilename: 'findings.md',
+                });
+                expect(links).toEqual([
+                    expect.objectContaining({
+                        targetType: 'workstream',
+                        targetId: workstream.id,
+                        role: 'attachment'
+                    })
+                ]);
+                expect(taskToolResult.content?.[0]?.text).toContain(`Task ${workstream.referenceLabel} not found`);
+            }
+            finally {
+                verifyCore.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('saves and deletes initiative attachments by initiative reference', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const initiative = core.createInitiative({ title: 'Attachment initiative' }, 'workspace-1');
+            core.close();
+            await callTool(projectRoot, 'cloud', 'save_initiative_attachment', {
+                id: initiative.referenceLabel,
+                filename: 'initiative-note.txt',
+                content: 'initiative attachment body'
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'cloud', 'get_initiative_attachments', { id: initiative.referenceLabel }));
+            const readBack = parseToolJson(await callTool(projectRoot, 'cloud', 'read_initiative_attachment', {
+                initiativeId: initiative.referenceLabel,
+                attachmentId: listed.attachments[0]?.attachmentId
+            }));
+            const deleted = parseToolJson(await callTool(projectRoot, 'cloud', 'delete_initiative_attachment', {
+                initiativeId: initiative.referenceLabel,
+                attachmentId: listed.attachments[0]?.attachmentId
+            }));
+            const afterDelete = parseToolJson(await callTool(projectRoot, 'cloud', 'get_initiative_attachments', { id: initiative.referenceLabel }));
+            const verifyCore = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            try {
+                const store = new WorkspaceAssetStore(verifyCore.getDatabaseAdapter(), verifyCore.getTenantId());
+                const asset = store.get(String(listed.attachments[0]?.assetId || ''), 'workspace-1');
+                expect(listed.initiativeId).toBe(initiative.id);
+                expect(listed.attachments).toHaveLength(1);
+                expect(listed.attachments[0]?.mimeType).toBe('text/plain');
+                expect(readBack.content).toContain('initiative attachment body');
+                expect(deleted.success).toBe(true);
+                expect(deleted.canonicalAssetDeleted).toBe(true);
+                expect(afterDelete.attachments).toEqual([]);
+                expect(asset?.deletedAt).toBeTruthy();
+            }
+            finally {
+                verifyCore.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('persists planning attachment descriptor payloads through update tools', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const initiative = core.createInitiative({ title: 'Descriptor initiative' }, 'workspace-1');
+            const workstream = core.createWorkstream({ title: 'Descriptor workstream' }, 'workspace-1');
+            core.close();
+            const initiativeAttachment = { path: 'https://example.com/initiative-register.md', caption: 'Initiative register' };
+            const workstreamAttachment = { path: 'https://example.com/workstream-register.md', caption: 'Workstream register' };
+            await callTool(projectRoot, 'cloud', 'update_initiative', {
+                id: initiative.referenceLabel,
+                attachments: [initiativeAttachment]
+            });
+            await callTool(projectRoot, 'cloud', 'update_workstream', {
+                id: workstream.referenceLabel,
+                attachments: [workstreamAttachment]
+            });
+            const initiativePayload = parseToolJson(await callTool(projectRoot, 'cloud', 'get_initiative', { id: initiative.referenceLabel }));
+            const workstreamPayload = parseToolJson(await callTool(projectRoot, 'cloud', 'get_workstream', { id: workstream.referenceLabel }));
+            expect(initiativePayload.initiative.attachments).toEqual([expect.objectContaining(initiativeAttachment)]);
+            expect(workstreamPayload.workstream.attachments).toEqual([expect.objectContaining(workstreamAttachment)]);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
     it('accepts task references for write and batch update tools', async () => {
         const projectRoot = createProjectRoot();
         try {
@@ -2645,6 +3893,52 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('accepts documented schedule helper arguments', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const first = core.createTask({ title: 'First documented schedule helper test' }, { workspaceId: 'workspace-1' });
+            const second = core.createTask({ title: 'Second documented schedule helper test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const board = parseToolJson(await callTool(projectRoot, 'local', 'get_schedule_board', {}));
+            expect(board.week).toMatch(/^\d{4}-W\d{2}$/);
+            const scheduled = parseToolJson(await callTool(projectRoot, 'local', 'schedule_task', {
+                taskId: first.referenceLabel,
+                date: '2099-01-05',
+                order: 3
+            }));
+            expect(scheduled.scheduling.persistedDate).toBe('2099-01-05');
+            expect(scheduled.scheduling.persistedOrderInDay).toBe(3);
+            await callTool(projectRoot, 'local', 'reorder_scheduled_tasks', {
+                date: '2099-01-05',
+                taskIds: [second.referenceLabel, first.referenceLabel]
+            });
+            await callTool(projectRoot, 'local', 'unschedule_task', {
+                taskId: first.referenceLabel
+            });
+            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).toBeNull();
+                expect(firstTask?.orderInDay).toBeNull();
+                expect(secondTask?.scheduledDate).toBe('2099-01-05');
+                expect(secondTask?.orderInDay).toBe(0);
+            }
+            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 {
@@ -2731,6 +4025,7 @@ describe('Taskforce MCP tool descriptions', () => {
                 label: 'Codex',
                 username: resolved.profile.username
             }));
+            expect(created.createdByActor.meta).not.toHaveProperty('profileToken');
             expect(created.taskEvents).toEqual(expect.arrayContaining([
                 expect.objectContaining({
                     action: 'task-created',
@@ -2743,6 +4038,7 @@ describe('Taskforce MCP tool descriptions', () => {
                     })
                 })
             ]));
+            expect(created.taskEvents[0].actorProfile.meta).not.toHaveProperty('profileToken');
         }
         finally {
             fs.rmSync(projectRoot, { recursive: true, force: true });
@@ -3216,6 +4512,61 @@ describe('Taskforce MCP annotated attachment tools', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('accepts exposed document and image helper argument names', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const { task, session } = seedAnnotatedAttachmentFixture(projectRoot);
+            const { asset } = seedDocumentReviewFixture(projectRoot);
+            const taskAttachments = parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', {
+                taskId: task.referenceLabel,
+            }, { workspaceId: 'workspace-1' }));
+            expect(taskAttachments.taskId).toBe(task.id);
+            expect(taskAttachments.referenceLabel).toBe(task.referenceLabel);
+            const document = parseToolJson(await callTool(projectRoot, 'cloud', 'get_document', {
+                id: 'D-123',
+            }, { workspaceId: 'workspace-1' }));
+            expect(document.document).toMatchObject({
+                assetId: asset.assetId,
+                referenceLabel: 'D-123',
+            });
+            const review = parseToolJson(await callTool(projectRoot, 'cloud', 'review_document', {
+                documentId: 'D-123',
+                prompt: 'Capture this as a first-pass review note.',
+            }, { workspaceId: 'workspace-1' }));
+            expect(review.document.assetId).toBe(asset.assetId);
+            expect(review.comments).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    body: 'Capture this as a first-pass review note.',
+                }),
+            ]));
+            expect(review.session.comments.some((comment) => comment.body === 'Capture this as a first-pass review note.')).toBe(true);
+            const image = parseToolJson(await callTool(projectRoot, 'cloud', 'get_image', {
+                id: 'I-1',
+            }, { workspaceId: 'workspace-1' }));
+            expect(image.image).toMatchObject({
+                assetId: 'asset-annotated-1',
+                referenceLabel: 'I-1',
+            });
+            const marker = parseToolJson(await callTool(projectRoot, 'cloud', 'add_annotated_attachment_marker', {
+                sessionId: session.id,
+                type: 'note',
+                text: 'Schema names should work end to end.',
+                x: 0.4,
+                y: 0.5,
+            }, { workspaceId: 'workspace-1' }));
+            expect(marker.marker).toMatchObject({
+                kind: 'text-note',
+                instruction: 'Schema names should work end to end.',
+            });
+            expect(marker.session.annotations.at(-1)).toMatchObject({
+                kind: 'text-note',
+                instruction: 'Schema names should work end to end.',
+            });
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
     it('creates image-note sessions and mutates markers through MCP', async () => {
         const projectRoot = createProjectRoot();
         try {