@taskforcehq/taskforce 0.3.301 → 0.3.302

package/dist/mcp/clientIntegrations.test.js

@@ -45,6 +45,8 @@ describe('clientIntegrations', () => {
             serverId: 'taskforce-workspace-alpha',
             aiProfileName: 'Automation Codex',
             aiProfileToken: 'tfp_automation_codex',
+            aiProfileIcon: 'Code2',
+            aiProfileColor: '#10a37f',
             aiProfileDescription: 'OpenAI Codex coding agent connected through MCP.',
             aiProfileRole: 'Coding Agent',
             aiProfileProvider: 'OpenAI',
@@ -57,26 +59,34 @@ describe('clientIntegrations', () => {
             tokenValue: '<<GENERATE_TOKEN>>',
             serverId: 'taskforce-workspace-alpha',
             aiProfileName: 'Automation Codex',
+            aiProfileIcon: 'Code2',
+            aiProfileColor: '#10a37f',
             aiProfileRole: 'Coding Agent',
         });
         expect(codex.renderedText).toContain('X-Taskforce-AI-Name = "Automation Codex"');
         expect(codex.renderedText).toContain('X-Taskforce-AI-Profile-Token = "tfp_automation_codex"');
+        expect(codex.renderedText).toContain('X-Taskforce-AI-Icon = "Code2"');
+        expect(codex.renderedText).toContain('X-Taskforce-AI-Color = "#10a37f"');
         expect(codex.renderedText).toContain('X-Taskforce-AI-Description = "OpenAI Codex coding agent connected through MCP."');
         expect(codex.renderedText).toContain('X-Taskforce-AI-Role = "Coding Agent"');
         expect(codex.renderedText).toContain('X-Taskforce-AI-Provider = "OpenAI"');
         expect(codex.renderedText).toContain('X-Taskforce-AI-Model = "Codex"');
         expect(codex.renderedText).toContain('X-Taskforce-AI-Surface-Type = "coding_tool"');
-        expect(codex.instructionText).toContain('automated AI workers');
+        expect(codex.instructionText).toContain('Use the generated config exactly as shown.');
+        expect(codex.instructionText).toContain('generated AI bootstrap headers');
         expect(vscode.serverConfig).toEqual({
             type: 'http',
             url: 'https://performance-app.taskforcehq.ai/mcp',
             headers: {
                 Authorization: 'Bearer <<GENERATE_TOKEN>>',
                 'X-Taskforce-AI-Name': 'Automation Codex',
+                'X-Taskforce-AI-Icon': 'Code2',
+                'X-Taskforce-AI-Color': '#10a37f',
                 'X-Taskforce-AI-Role': 'Coding Agent',
             }
         });
-        expect(vscode.instructionText).toContain('automated AI workers');
+        expect(vscode.instructionText).toContain('Use the generated config exactly as shown.');
+        expect(vscode.instructionText).toContain('generated AI bootstrap headers');
     });
     it('builds JSON text config for OpenClaw using mcp.servers', () => {
         const integration = buildCloudMcpClientIntegration({
@@ -97,6 +107,22 @@ describe('clientIntegrations', () => {
         });
         expect(integration.instructionText).toContain('~/.openclaw/openclaw.json');
     });
+    it('keeps OAuth connector instructions focused on the URL flow instead of generated config language', () => {
+        const claudeDesktop = buildCloudMcpClientIntegration({
+            clientId: 'claude-desktop',
+            endpoint: 'https://performance-app.taskforcehq.ai/mcp',
+            tokenValue: '<<GENERATE_TOKEN>>',
+            serverId: 'taskforce-workspace-alpha',
+        });
+        const chatgptDesktop = buildCloudMcpClientIntegration({
+            clientId: 'chatgpt-desktop',
+            endpoint: 'https://performance-app.taskforcehq.ai/mcp',
+            tokenValue: '<<GENERATE_TOKEN>>',
+            serverId: 'taskforce-workspace-alpha',
+        });
+        expect(claudeDesktop.instructionText).not.toContain('generated config exactly as shown');
+        expect(chatgptDesktop.instructionText).not.toContain('generated config exactly as shown');
+    });
     it('builds command config for Gemini CLI using http transport', () => {
         const integration = buildCloudMcpClientIntegration({
             clientId: 'gemini-cli',

package/dist/mcp/clientProfileDefaults.d.ts

@@ -0,0 +1,12 @@
+import type { McpClientId } from './clientIntegrations.js';
+import type { AiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
+export interface AiProfileMetadataDefaults {
+    icon: string | null;
+    color: string | null;
+    description: string | null;
+    role: string | null;
+    provider: string | null;
+    model: string | null;
+    surfaceType: AiProfileSurfaceType | null;
+}
+export declare function getDefaultAiProfileMetadataForClient(clientId: McpClientId): AiProfileMetadataDefaults;

package/dist/mcp/clientProfileDefaults.js

@@ -0,0 +1,37 @@
+const CLIENT_LABELS = {
+    cline: 'Cline',
+    windsurf: 'Windsurf',
+    antigravity: 'Antigravity',
+    openclaw: 'OpenClaw',
+};
+export function getDefaultAiProfileMetadataForClient(clientId) {
+    switch (clientId) {
+        case 'codex':
+            return { icon: 'Code2', color: '#10a37f', description: 'OpenAI Codex coding agent connected through MCP.', role: 'Coding Agent', provider: 'OpenAI', model: 'Codex', surfaceType: 'coding_tool' };
+        case 'chatgpt-desktop':
+            return { icon: 'MessageSquare', color: '#10a37f', description: 'ChatGPT desktop app connected through the Taskforce MCP connector.', role: 'AI Assistant', provider: 'OpenAI', model: 'ChatGPT', surfaceType: 'chat_app' };
+        case 'claude-code':
+            return { icon: 'Sparkles', color: '#d97706', description: 'Claude Code coding agent connected through MCP.', role: 'Coding Agent', provider: 'Anthropic', model: 'Claude Code', surfaceType: 'coding_tool' };
+        case 'claude-desktop':
+            return { icon: 'MessageSquareMore', color: '#d97706', description: 'Claude Desktop connected through the Taskforce MCP connector.', role: 'AI Assistant', provider: 'Anthropic', model: 'Claude', surfaceType: 'chat_app' };
+        case 'gemini-cli':
+            return { icon: 'Gem', color: '#2563eb', description: 'Gemini CLI coding agent connected through MCP.', role: 'Coding Agent', provider: 'Google', model: 'Gemini', surfaceType: 'coding_tool' };
+        case 'vscode':
+            return { icon: 'Code2', color: '#2563eb', description: 'VS Code MCP-connected coding agent.', role: 'Coding Agent', provider: null, model: null, surfaceType: 'ide' };
+        case 'cline':
+        case 'windsurf':
+        case 'antigravity':
+        case 'openclaw':
+            return {
+                icon: 'Bot',
+                color: '#8b5cf6',
+                description: `${CLIENT_LABELS[clientId] || 'MCP'} coding agent connected through MCP.`,
+                role: 'Coding Agent',
+                provider: null,
+                model: null,
+                surfaceType: 'coding_tool',
+            };
+        default:
+            return { icon: null, color: null, description: null, role: null, provider: null, model: null, surfaceType: null };
+    }
+}

package/dist/mcp/runtime.d.ts

@@ -1,6 +1,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { McpAccessTokenScope, TaskforceCore } from '../core/Taskforce.js';
+import { type AiProfileBootstrapConfig } from './aiProfileBootstrap.js';
 export interface TaskforceMcpServerOptions {
     projectRoot?: string;
     tenantId?: string;
@@ -13,13 +14,15 @@ export interface TaskforceMcpServerOptions {
         scopes?: McpAccessTokenScope[] | null;
         userId?: string | null;
         tokenId?: string | null;
-        aiProfileToken?: string | null;
-        aiProfileName?: string | null;
-        aiProfileDescription?: string | null;
-        aiProfileRole?: string | null;
-        aiProfileProvider?: string | null;
-        aiProfileModel?: string | null;
-        aiProfileSurfaceType?: string | null;
+        aiProfileToken?: AiProfileBootstrapConfig['aiProfileToken'];
+        aiProfileName?: AiProfileBootstrapConfig['aiProfileName'];
+        aiProfileIcon?: AiProfileBootstrapConfig['aiProfileIcon'];
+        aiProfileColor?: AiProfileBootstrapConfig['aiProfileColor'];
+        aiProfileDescription?: AiProfileBootstrapConfig['aiProfileDescription'];
+        aiProfileRole?: AiProfileBootstrapConfig['aiProfileRole'];
+        aiProfileProvider?: AiProfileBootstrapConfig['aiProfileProvider'];
+        aiProfileModel?: AiProfileBootstrapConfig['aiProfileModel'];
+        aiProfileSurfaceType?: AiProfileBootstrapConfig['aiProfileSurfaceType'];
         actorType?: 'local' | 'user' | 'token' | 'oauth';
         requestId?: string | null;
         ip?: string | null;

package/dist/mcp/runtime.js

@@ -6,6 +6,7 @@ import * as path from 'path';
 import { createHash, randomUUID } from 'node:crypto';
 import { TaskforceCore, TaskforceRuleError } from '../core/Taskforce.js'; // Note .js extension for ESM
 import { COMPLEXITY_OPTIONS, resolveNumberOption, resolveStringOption, STATUS_OPTIONS } from './optionResolution.js';
+import { buildResolveAiProfileInputFromBootstrap } from './aiProfileBootstrap.js';
 import { validateStructuredDocForAttach } from './structuredDocValidation.js';
 import { validateStructuredCommentForAdd } from './structuredCommentValidation.js';
 import { resolveDatabaseConfigFromEnv } from '../storage/providerConfig.js';
@@ -16,9 +17,9 @@ import { ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY, resolveAppGateAccess, } fr
 import { getDocumentReferenceLabel, parseDocumentReference } from '../utils/documentReferences.js';
 import { getImageReferenceLabel, parseImageReference } from '../utils/imageReferences.js';
 import { inferCanonicalAssetKind, isValidCanonicalDocumentAsset } from '../utils/canonicalAssetKind.js';
+import { getTaskReferenceLabel, shouldUseProvisionalTaskReferences } from '../utils/taskReferences.js';
 import { AI_PROFILE_SURFACE_TYPES, parseAiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
 import { formatWorkstreamReference, resolveInitiativeReference, parseWorkstreamReference, } from '../utils/planningReferences.js';
-import { getTaskReferenceLabel } from '../utils/taskReferences.js';
 import { MCP_TOOL_PERMISSIONS, MCP_WRITE_TOOL_NAMES } from './toolRegistry.js';
 export function isMcpWriteToolName(name) {
     return MCP_WRITE_TOOL_NAMES.has(String(name || '').trim());
@@ -71,7 +72,7 @@ function resolveRecoverableToolError(error) {
             code: 'AI_PROFILE_REQUIRED',
             nextTool: 'resolve_profile',
             suggestedArgs: {},
-            retryHint: 'Call resolve_profile, store the returned profileToken, and pass profileToken on later mutating calls if the client is stateless.'
+            retryHint: 'Call get_current_profile to inspect binding state first, or call resolve_profile to bind an AI identity. Only pass profileToken on later mutating calls if your client is stateless.'
         };
     }
     if (/^Invalid AI profile token\./i.test(message)) {
@@ -80,7 +81,7 @@ function resolveRecoverableToolError(error) {
             code: 'INVALID_AI_PROFILE_TOKEN',
             nextTool: 'resolve_profile',
             suggestedArgs: {},
-            retryHint: 'Call resolve_profile again to obtain a fresh profileToken, then retry the original mutating tool call.'
+            retryHint: 'Call get_current_profile to confirm whether ambient identity is already bound. If not, call resolve_profile again to obtain a fresh profileToken, then retry the original mutating tool call.'
         };
     }
     if (error instanceof TaskforceRuleError) {
@@ -586,7 +587,7 @@ export function createTaskforceMcpServer(options = {}) {
             },
             tools: {},
         },
-        instructions: `You are an AI collaborator connected to Taskforce, a shared task management system for AI-developer pairs.\n\nIMPORTANT: At the start of any session, call resolve_profile before attempting any mutating Taskforce tools. Pass your name and a profileToken if you received one in a previous session. Store the returned profileToken for reuse across sessions. Use the returned profile id as the assignee or author on tasks and comments you create.\n\nStateless client pattern: call resolve_profile, save the returned profileToken, and include profileToken on later mutating tool calls if your MCP client does not preserve session identity between calls.\n\nAutomation-friendly connection pattern: if your MCP connection is configured with x-taskforce-ai-name and optionally x-taskforce-ai-profile-token headers, Taskforce can auto-bind that AI identity for get_current_profile and later writes without requiring profileToken on every tool call.\n\nWhen setting resolve_profile.surfaceType, classify yourself by the kind of identity you are registering: use agent for a persistent named AI collaborator in Taskforce, coding_tool for the coding surface or terminal tool itself, chat_app for a conversational app identity, ide for an IDE-native copilot identity, and other only when none of those fit. If you are unsure and you are registering a named collaborator such as a teammate-style AI persona, choose agent.\n\nTo get tasks assigned to yourself, call get_current_profile, then use the returned suggestedArgs with list_tasks. When you begin active work on a tracked task, prefer start_task. It sets the task to in-progress and claims it for your AI profile when the task is currently unassigned. When work on a tracked task is complete, prefer finish_task for the final handoff: use outcome='review' when the next step is human validation or approval, and use outcome='done' only when no explicit human action is requested. Do not leave a task in-progress after reporting completed implementation unless the user explicitly wants more work to continue in the same task.\n\nTaxonomy rule: always call get_config before setting category, type, priority, approach, status, or complexity. Do not rely on remembered enum values.\n\nUse identifier prefixes to choose the correct retrieval path: T-123 goes to task tools such as get_task, IN-123 goes to initiative tools such as get_initiative, WS-123 goes to workstream tools such as get_workstream, I-123 goes to image tools such as get_image, and D-123 goes to document tools such as get_document. Do not send I-123 or D-123 identifiers to get_task.\n\nFor annotated images, use search_images first when you know only a keyword, filename, or rough title. Once you have the exact identifier, call get_image, then use get_annotated_attachment_sessions to list saved sessions, then use read_annotated_attachment_payload for the structured annotation payload.\n\nFor documents, use search_documents first when you know only a keyword, filename, or rough title. Once you have the exact identifier, call get_document, then read_document_content to inspect the document body. For a lower-friction review flow, prefer review_document; otherwise use get_document_review_sessions or create_document_review_session, then add_document_review_comment to record review feedback.`,
+        instructions: `You are an AI collaborator connected to Taskforce, a shared task management system for AI-developer pairs.\n\nIMPORTANT: Before mutating Taskforce data, ensure Taskforce knows which AI profile you are acting as. The preferred path is ambient session binding: if your MCP connection is configured with x-taskforce-ai-name and optionally x-taskforce-ai-profile-token headers, Taskforce can auto-bind that AI identity for get_current_profile and later writes. If no AI identity is currently bound, call resolve_profile with your name. Reuse the returned profileToken across sessions, especially for stateless clients.\n\nStateless client pattern: call resolve_profile, save the returned profileToken, and include profileToken on later mutating tool calls only when your MCP client does not preserve session identity between calls.\n\nTo inspect your current attribution state before writes, call get_current_profile. It reports whether identity is bound, how it was resolved, and the suggested args to use with list_tasks.\n\nWhen setting resolve_profile.surfaceType, classify yourself by the kind of identity you are registering: use agent for a persistent named AI collaborator in Taskforce, coding_tool for the coding surface or terminal tool itself, chat_app for a conversational app identity, ide for an IDE-native copilot identity, and other only when none of those fit. If you are unsure and you are registering a named collaborator such as a teammate-style AI persona, choose agent.\n\nTo get tasks assigned to yourself, call get_current_profile, then use the returned suggestedArgs with list_tasks. When you begin active work on a tracked task, prefer start_task. It sets the task to in-progress and claims it for your AI profile when the task is currently unassigned. When work on a tracked task is complete, prefer finish_task for the final handoff: use outcome='review' when the next step is human validation or approval, and use outcome='done' only when no explicit human action is requested. Do not leave a task in-progress after reporting completed implementation unless the user explicitly wants more work to continue in the same task.\n\nTaxonomy rule: always call get_config before setting category, type, priority, approach, status, or complexity. Do not rely on remembered enum values.\n\nUse identifier prefixes to choose the correct retrieval path: T-123 goes to task tools such as get_task, IN-123 goes to initiative tools such as get_initiative, WS-123 goes to workstream tools such as get_workstream, I-123 goes to image tools such as get_image, and D-123 goes to document tools such as get_document. Do not send I-123 or D-123 identifiers to get_task.\n\nFor annotated images, use search_images first when you know only a keyword, filename, or rough title. Once you have the exact identifier, call get_image, then use get_annotated_attachment_sessions to list saved sessions, then use read_annotated_attachment_payload for the structured annotation payload.\n\nFor documents, use search_documents first when you know only a keyword, filename, or rough title. Once you have the exact identifier, call get_document, then read_document_content to inspect the document body. For a lower-friction review flow, prefer review_document; otherwise use get_document_review_sessions or create_document_review_session, then add_document_review_comment to record review feedback.`,
     });
     const TOOL_PERMISSIONS = MCP_TOOL_PERMISSIONS;
     const RESOURCE_PERMISSIONS = {
@@ -923,6 +924,8 @@ export function createTaskforceMcpServer(options = {}) {
     const auditTokenId = options.auth?.tokenId ? String(options.auth.tokenId).trim() : null;
     const configuredAiProfileToken = options.auth?.aiProfileToken ? String(options.auth.aiProfileToken).trim() || null : null;
     const configuredAiProfileName = options.auth?.aiProfileName ? String(options.auth.aiProfileName).trim() || null : null;
+    const configuredAiProfileIcon = options.auth?.aiProfileIcon ? String(options.auth.aiProfileIcon).trim() || null : null;
+    const configuredAiProfileColor = options.auth?.aiProfileColor ? String(options.auth.aiProfileColor).trim() || null : null;
     const configuredAiProfileDescription = options.auth?.aiProfileDescription ? String(options.auth.aiProfileDescription).trim() || null : null;
     const configuredAiProfileRole = options.auth?.aiProfileRole ? String(options.auth.aiProfileRole).trim() || null : null;
     const configuredAiProfileProvider = options.auth?.aiProfileProvider ? String(options.auth.aiProfileProvider).trim() || null : null;
@@ -932,6 +935,7 @@ export function createTaskforceMcpServer(options = {}) {
     const auditIp = options.auth?.ip ? String(options.auth.ip).trim() || null : null;
     const auditUserAgent = options.auth?.userAgent ? String(options.auth.userAgent).trim() || null : null;
     let activeAiProfileId = null;
+    let activeAiBindingSource = null;
     function getEligibleAssigneeActors() {
         return core.listAssignableActors(ACTIVE_WORKSPACE_ID)
             .filter((actor) => String(actor.id || '').trim().toLowerCase() !== 'agent')
@@ -1084,20 +1088,24 @@ export function createTaskforceMcpServer(options = {}) {
         const token = String(args.profileToken || '').trim();
         return token || null;
     }
+    function getCurrentAiBindingSource() {
+        if (!activeAiProfileId)
+            return 'none';
+        return activeAiBindingSource || 'session';
+    }
     function buildConfiguredAiProfileResolveInput(includeToken = true) {
-        if (!configuredAiProfileName)
-            return null;
         const configuredSurfaceType = parseAiProfileSurfaceType(configuredAiProfileSurfaceType);
-        return {
-            workspaceId: ACTIVE_WORKSPACE_ID,
-            name: configuredAiProfileName,
-            ...(includeToken && configuredAiProfileToken ? { profileToken: configuredAiProfileToken } : {}),
-            ...(configuredAiProfileDescription ? { description: configuredAiProfileDescription } : {}),
-            ...(configuredAiProfileRole ? { role: configuredAiProfileRole } : {}),
-            ...(configuredAiProfileProvider ? { provider: configuredAiProfileProvider } : {}),
-            ...(configuredAiProfileModel ? { model: configuredAiProfileModel } : {}),
-            ...(configuredSurfaceType ? { surfaceType: configuredSurfaceType } : {}),
-        };
+        return buildResolveAiProfileInputFromBootstrap(ACTIVE_WORKSPACE_ID, {
+            aiProfileToken: configuredAiProfileToken,
+            aiProfileName: configuredAiProfileName,
+            aiProfileIcon: configuredAiProfileIcon,
+            aiProfileColor: configuredAiProfileColor,
+            aiProfileDescription: configuredAiProfileDescription,
+            aiProfileRole: configuredAiProfileRole,
+            aiProfileProvider: configuredAiProfileProvider,
+            aiProfileModel: configuredAiProfileModel,
+            aiProfileSurfaceType: configuredSurfaceType,
+        }, includeToken);
     }
     function ensureResolvedProfileFromConnection(defaults) {
         if (activeAiProfileId)
@@ -1110,6 +1118,7 @@ export function createTaskforceMcpServer(options = {}) {
                 try {
                     const resolved = core.resolveAiProfile(configuredResolveInput);
                     activeAiProfileId = resolved.profile.id;
+                    activeAiBindingSource = 'connection_bootstrap';
                     return;
                 }
                 catch {
@@ -1122,6 +1131,7 @@ export function createTaskforceMcpServer(options = {}) {
             });
             if (profile) {
                 activeAiProfileId = profile.id;
+                activeAiBindingSource = 'connection_bootstrap';
                 return;
             }
             if (!allowCreateFromName || !configuredAiProfileName) {
@@ -1131,6 +1141,7 @@ export function createTaskforceMcpServer(options = {}) {
         if (allowCreateFromName && configuredResolveFallbackInput) {
             const resolved = core.resolveAiProfile(configuredResolveFallbackInput);
             activeAiProfileId = resolved.profile.id;
+            activeAiBindingSource = 'connection_bootstrap';
         }
     }
     function ensureResolvedProfileForTool(name, args) {
@@ -1151,6 +1162,7 @@ export function createTaskforceMcpServer(options = {}) {
         });
         if (profile) {
             activeAiProfileId = profile.id;
+            activeAiBindingSource = 'token_lookup';
             return;
         }
         const configuredResolveInput = buildConfiguredAiProfileResolveInput(false);
@@ -1158,6 +1170,7 @@ export function createTaskforceMcpServer(options = {}) {
             try {
                 const resolved = core.resolveAiProfile(configuredResolveInput);
                 activeAiProfileId = resolved.profile.id;
+                activeAiBindingSource = 'connection_bootstrap';
                 return;
             }
             catch {
@@ -2038,8 +2051,8 @@ export function createTaskforceMcpServer(options = {}) {
                     type: "object",
                     properties: {
                         name: { type: "string", description: "Display name for the AI collaborator." },
-                        icon: { type: "string", description: "Optional icon name or emoji saved with the AI profile." },
-                        color: { type: "string", description: "Optional profile color saved with the AI profile." },
+                        icon: { type: "string", description: "Optional icon name or emoji saved with the AI profile. Omit to leave unchanged when profileToken is provided." },
+                        color: { type: "string", description: "Optional profile color saved with the AI profile. Omit to leave unchanged when profileToken is provided." },
                         description: { type: "string", description: "Optional short description stored on the AI profile. Omit to leave unchanged when profileToken is provided." },
                         role: { type: "string", description: "Optional role label stored on the AI profile. Omit to leave unchanged when profileToken is provided." },
                         provider: { type: "string", description: "Optional provider name stored as secondary diagnostic metadata on the AI profile. Omit to leave unchanged when profileToken is provided." },
@@ -3311,6 +3324,7 @@ export function createTaskforceMcpServer(options = {}) {
                         profileToken: typeof profileToken === 'string' ? profileToken : null
                     });
                     activeAiProfileId = resolved.profile.id;
+                    activeAiBindingSource = 'session';
                     recordMcpWriteAudit('resolve_profile', {
                         profileId: resolved.profile.id,
                         created: resolved.created
@@ -3358,6 +3372,7 @@ export function createTaskforceMcpServer(options = {}) {
                     let profile = activeAiProfileId
                         ? core.listAiProfiles(ACTIVE_WORKSPACE_ID).find((entry) => entry.id === activeAiProfileId) || null
                         : null;
+                    let bindingSource = getCurrentAiBindingSource();
                     if (!profile && typeof profileToken === 'string' && profileToken.trim()) {
                         profile = core.getAiProfileByToken({
                             workspaceId: ACTIVE_WORKSPACE_ID,
@@ -3366,6 +3381,7 @@ export function createTaskforceMcpServer(options = {}) {
                         if (!profile) {
                             throw new Error('Invalid AI profile token. Call resolve_profile again and retry.');
                         }
+                        bindingSource = 'token_lookup';
                     }
                     return {
                         content: [{
@@ -3373,6 +3389,8 @@ export function createTaskforceMcpServer(options = {}) {
                                 text: JSON.stringify({
                                     workspaceId: ACTIVE_WORKSPACE_ID,
                                     identityBound: Boolean(activeAiProfileId),
+                                    bindingSource,
+                                    writeReady: Boolean(profile),
                                     profileToken: profile?.profileToken ?? null,
                                     profile: profile ? buildAiProfileDescriptor(profile) : null,
                                     taskFilter: profile ? { assignee: profile.id } : null,
@@ -4779,7 +4797,11 @@ export function createTaskforceMcpServer(options = {}) {
                             ...createArgs,
                             ...normalized,
                             createdBy: getActiveMcpCreatedBy()
-                        }, { workspaceId: ACTIVE_WORKSPACE_ID, actorRef: getActiveMcpActorRef() });
+                        }, {
+                            workspaceId: ACTIVE_WORKSPACE_ID,
+                            actorRef: getActiveMcpActorRef(),
+                            provisionalLocalReference: shouldUseProvisionalTaskReferences(runtimeMode)
+                        });
                         recordMcpWriteAudit('create_task', {
                             taskId: task?.id || null,
                             title: task?.title || null

package/dist/mcp/runtime.test.js

@@ -73,6 +73,8 @@ async function callTool(projectRoot, runtimeMode, name, args, options) {
                 actorType: 'oauth',
                 aiProfileToken: options?.authAiProfileToken || null,
                 aiProfileName: options?.authAiProfileName || null,
+                aiProfileIcon: options?.authAiProfileIcon || null,
+                aiProfileColor: options?.authAiProfileColor || null,
                 aiProfileDescription: options?.authAiProfileDescription || null,
                 aiProfileRole: options?.authAiProfileRole || null,
                 aiProfileProvider: options?.authAiProfileProvider || null,
@@ -713,6 +715,8 @@ describe('Taskforce MCP tool descriptions', () => {
                 model: 'Codex',
                 surfaceType: 'coding_tool'
             }));
+            expect(currentProfile.bindingSource).toBe('connection_bootstrap');
+            expect(currentProfile.writeReady).toBe(true);
         }
         finally {
             fs.rmSync(projectRoot, { recursive: true, force: true });
@@ -788,6 +792,8 @@ describe('Taskforce MCP tool descriptions', () => {
                 authAiProfileName: 'Automation Codex'
             }));
             expect(currentProfile.identityBound).toBe(true);
+            expect(currentProfile.bindingSource).toBe('connection_bootstrap');
+            expect(currentProfile.writeReady).toBe(true);
             expect(currentProfile.profileToken).toMatch(/^tfp_/);
             expect(currentProfile.profile).toEqual(expect.objectContaining({
                 name: 'Automation Codex',
@@ -817,6 +823,27 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('reports token_lookup binding when get_current_profile is inspected with an explicit profileToken', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const resolved = parseToolJson(await callTool(projectRoot, 'local', 'resolve_profile', {
+                name: 'Codex'
+            }, { resolveProfile: false }));
+            const payload = parseToolJson(await callTool(projectRoot, 'local', 'get_current_profile', {
+                profileToken: resolved.profile.profileToken,
+            }, { resolveProfile: false }));
+            expect(payload.identityBound).toBe(false);
+            expect(payload.bindingSource).toBe('token_lookup');
+            expect(payload.writeReady).toBe(true);
+            expect(payload.profile).toEqual(expect.objectContaining({
+                id: resolved.profile.id,
+                profileToken: resolved.profile.profileToken,
+            }));
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
     it('recovers from an invalid per-call profileToken when the connection has a valid AI name', async () => {
         const projectRoot = createProjectRoot();
         try {
@@ -1214,6 +1241,8 @@ describe('Taskforce MCP tool descriptions', () => {
                 }
             }, {}));
             expect(payload.identityBound).toBe(true);
+            expect(payload.bindingSource).toBe('session');
+            expect(payload.writeReady).toBe(true);
             expect(payload.profile).toEqual(expect.objectContaining({
                 id: resolved.profile.id,
                 username: resolved.profile.username,
@@ -1235,6 +1264,8 @@ describe('Taskforce MCP tool descriptions', () => {
                 resolveProfile: false
             }));
             expect(payload.identityBound).toBe(false);
+            expect(payload.bindingSource).toBe('none');
+            expect(payload.writeReady).toBe(false);
             expect(payload.profile).toBeNull();
             expect(payload.taskFilter).toBeNull();
             expect(payload.nextTool).toBe('resolve_profile');
@@ -1251,13 +1282,29 @@ describe('Taskforce MCP tool descriptions', () => {
             const payload = parseToolJson(await callTool(projectRoot, 'cloud', 'get_current_profile', {}, {
                 workspaceId: 'workspace-1',
                 resolveProfile: false,
-                authAiProfileName: 'Automation Codex'
+                authAiProfileName: 'Automation Codex',
+                authAiProfileIcon: 'Code2',
+                authAiProfileColor: '#10a37f',
+                authAiProfileDescription: 'OpenAI Codex coding agent connected through MCP.',
+                authAiProfileRole: 'Coding Agent',
+                authAiProfileProvider: 'OpenAI',
+                authAiProfileModel: 'Codex',
+                authAiProfileSurfaceType: 'coding_tool'
             }));
             expect(payload.identityBound).toBe(true);
+            expect(payload.bindingSource).toBe('connection_bootstrap');
+            expect(payload.writeReady).toBe(true);
             expect(payload.profile).toEqual(expect.objectContaining({
                 name: 'Automation Codex',
                 username: 'automation-codex',
-                profileToken: expect.stringMatching(/^tfp_/)
+                profileToken: expect.stringMatching(/^tfp_/),
+                icon: 'Code2',
+                color: '#10a37f',
+                description: 'OpenAI Codex coding agent connected through MCP.',
+                role: 'Coding Agent',
+                provider: 'OpenAI',
+                model: 'Codex',
+                surfaceType: 'coding_tool'
             }));
             expect(payload.taskFilter).toEqual({ assignee: payload.profile.id });
             expect(payload.nextTool).toBe('list_tasks');

package/dist/migrations/taskSchemaMigrations.js

@@ -122,9 +122,13 @@ export function ensureAssigneeTaskSchema(db) {
 export function ensureTaskReferenceSchema(db) {
     const columns = db.prepare(`PRAGMA table_info(tasks)`).all();
     const hasReferenceNumberColumn = columns.some((c) => c.name === 'reference_number');
+    const hasLocalReferenceNumberColumn = columns.some((c) => c.name === 'local_reference_number');
     if (!hasReferenceNumberColumn) {
         db.exec(`ALTER TABLE tasks ADD COLUMN reference_number INTEGER`);
     }
+    if (!hasLocalReferenceNumberColumn) {
+        db.exec(`ALTER TABLE tasks ADD COLUMN local_reference_number INTEGER`);
+    }
     db.exec(`
         CREATE TABLE IF NOT EXISTS workspace_task_reference_sequences (
             tenant_id TEXT NOT NULL DEFAULT 'default',
@@ -132,6 +136,12 @@ export function ensureTaskReferenceSchema(db) {
             next_reference_number INTEGER NOT NULL DEFAULT 0,
             PRIMARY KEY (tenant_id, workspace_id)
         );
+        CREATE TABLE IF NOT EXISTS workspace_local_task_reference_sequences (
+            tenant_id TEXT NOT NULL DEFAULT 'default',
+            workspace_id TEXT NOT NULL DEFAULT 'default',
+            next_reference_number INTEGER NOT NULL DEFAULT 0,
+            PRIMARY KEY (tenant_id, workspace_id)
+        );
     `);
     const workspaceRows = db.prepare(`
         SELECT DISTINCT
@@ -141,7 +151,7 @@ export function ensureTaskReferenceSchema(db) {
         ORDER BY tenant_id ASC, workspace_id ASC
     `).all();
     const selectRows = db.prepare(`
-        SELECT id, reference_number, created_at
+        SELECT id, reference_number, local_reference_number, created_at
         FROM tasks
         WHERE tenant_id = ? AND workspace_id = ?
         ORDER BY created_at ASC, id ASC
@@ -171,11 +181,20 @@ export function ensureTaskReferenceSchema(db) {
             const currentReferenceNumber = Number.isFinite(rawReferenceNumber) && rawReferenceNumber > 0
                 ? Math.floor(rawReferenceNumber)
                 : null;
+            const rawLocalReferenceNumber = Number(row.local_reference_number);
+            const currentLocalReferenceNumber = Number.isFinite(rawLocalReferenceNumber) && rawLocalReferenceNumber > 0
+                ? Math.floor(rawLocalReferenceNumber)
+                : null;
             if (currentReferenceNumber && !seen.has(currentReferenceNumber)) {
                 seen.add(currentReferenceNumber);
                 nextReferenceNumber = Math.max(nextReferenceNumber, currentReferenceNumber);
                 continue;
             }
+            // Provisional local references are intentionally non-canonical and should
+            // not be promoted to T-### during schema repair or restart migrations.
+            if (!currentReferenceNumber && currentLocalReferenceNumber) {
+                continue;
+            }
             nextReferenceNumber += 1;
             seen.add(nextReferenceNumber);
             updateReference.run(nextReferenceNumber, tenantId, workspaceId, taskId);
@@ -185,6 +204,8 @@ export function ensureTaskReferenceSchema(db) {
     db.exec(`
         CREATE UNIQUE INDEX IF NOT EXISTS idx_tasks_workspace_reference
         ON tasks(tenant_id, workspace_id, reference_number);
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_tasks_workspace_local_reference
+        ON tasks(tenant_id, workspace_id, local_reference_number);
     `);
 }
 export function ensureWorkspaceSchema(db) {
@@ -215,6 +236,23 @@ export function ensureWorkspaceSchema(db) {
             updated_at TEXT
         );
 
+        CREATE TABLE IF NOT EXISTS user_avatar_upload_drafts (
+            draft_id TEXT PRIMARY KEY,
+            tenant_id TEXT NOT NULL DEFAULT 'default',
+            user_id TEXT NOT NULL,
+            storage_key TEXT NOT NULL,
+            mime_type TEXT NOT NULL,
+            original_filename TEXT NOT NULL,
+            size_bytes INTEGER NOT NULL DEFAULT 0,
+            storage_provider TEXT NOT NULL DEFAULT 'local',
+            finalized_at TEXT,
+            consumed_at TEXT,
+            discarded_at TEXT,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+        );
+
         CREATE TABLE IF NOT EXISTS auth_tokens (
             id TEXT PRIMARY KEY,
             tenant_id TEXT NOT NULL DEFAULT 'default',
@@ -356,6 +394,20 @@ export function ensureWorkspaceSchema(db) {
     if (!hasWorkspaceIdColumn) {
         db.exec(`ALTER TABLE auth_tokens ADD COLUMN workspace_id TEXT`);
     }
+    if (db.provider === 'postgres') {
+        try {
+            db.exec(`ALTER TABLE user_avatar_upload_drafts ADD COLUMN IF NOT EXISTS consumed_at TEXT`);
+        }
+        catch {
+            // Best-effort repair for older dev databases.
+        }
+    }
+    else {
+        const avatarDraftColumns = db.prepare(`PRAGMA table_info(user_avatar_upload_drafts)`).all();
+        if (avatarDraftColumns.length > 0 && !avatarDraftColumns.some((c) => c.name === 'consumed_at')) {
+            db.exec(`ALTER TABLE user_avatar_upload_drafts ADD COLUMN consumed_at TEXT`);
+        }
+    }
     const mcpTokenColumns = db.prepare(`PRAGMA table_info(mcp_access_tokens)`).all();
     if (mcpTokenColumns.length > 0) {
         const requiredColumns = [

package/dist/qaOpen.test.d.ts

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

package/dist/qaOpen.test.js

@@ -0,0 +1,56 @@
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+// @ts-ignore - JS helper module without generated .d.ts; covered by focused tests.
+import { assertQaProjectRootSafe, matchExpectedWorkspace, parseEnvFileContents, parseQaArgs, resolveExpectedWorkspace, resolveQaPaths } from '../scripts/qa-open-lib.mjs';
+describe('qa open helper library', () => {
+    it('derives a stable QA root layout for an agent', () => {
+        const homeDir = path.join(os.tmpdir(), 'qa-open-test-home');
+        const paths = resolveQaPaths({ agentId: 'Codex Main', homeDir });
+        expect(paths.agentId).toBe('codex-main');
+        expect(paths.root).toContain(path.join('.taskforce', 'qa', 'codex-main'));
+        expect(paths.projectRoot).toContain(path.join('.taskforce', 'qa', 'codex-main', 'project'));
+        expect(paths.playwrightStorageState).toContain(path.join('.taskforce', 'qa', 'codex-main', 'playwright-auth.json'));
+    });
+    it('parses env files with comments, export statements, and quoted values', () => {
+        const env = parseEnvFileContents(`
+            # comment
+            export TASKFORCE_E2E_EMAIL="codex@example.com"
+            TASKFORCE_E2E_PASSWORD='secret'
+            TASKFORCE_QA_EXPECTED_WORKSPACE_SLUG=codex-qa
+        `);
+        expect(env.TASKFORCE_E2E_EMAIL).toBe('codex@example.com');
+        expect(env.TASKFORCE_E2E_PASSWORD).toBe('secret');
+        expect(env.TASKFORCE_QA_EXPECTED_WORKSPACE_SLUG).toBe('codex-qa');
+    });
+    it('rejects QA roots inside the repository', () => {
+        const repoRoot = '/repo/taskforce';
+        expect(() => assertQaProjectRootSafe('/repo/taskforce', repoRoot)).toThrow(/inside the repository/i);
+        expect(() => assertQaProjectRootSafe('/repo/taskforce/tmp/qa', repoRoot)).toThrow(/inside the repository/i);
+        expect(() => assertQaProjectRootSafe('/tmp/taskforce-qa', repoRoot)).not.toThrow();
+    });
+    it('matches expected workspace by slug against the current workspace id', () => {
+        const match = matchExpectedWorkspace({
+            currentWorkspaceId: 'workspace-2',
+            workspaces: [
+                { id: 'workspace-1', slug: 'alpha' },
+                { id: 'workspace-2', slug: 'beta' }
+            ]
+        }, { workspaceId: null, workspaceSlug: 'beta' });
+        expect(match.ok).toBe(true);
+    });
+    it('builds args and expected workspace from env', () => {
+        const parsed = parseQaArgs([], {
+            TASKFORCE_QA_AGENT: 'Claude QA',
+            TASKFORCE_QA_MODE: 'staging',
+            TASKFORCE_QA_PORT: '5199'
+        });
+        expect(parsed.agentId).toBe('claude-qa');
+        expect(parsed.mode).toBe('staging');
+        expect(parsed.preferredPort).toBe(5199);
+        const expected = resolveExpectedWorkspace({
+            TASKFORCE_QA_EXPECTED_WORKSPACE_ID: 'workspace-123'
+        });
+        expect(expected).toEqual({ workspaceId: 'workspace-123', workspaceSlug: null });
+    });
+});

package/dist/server/index.cookieProxy.test.js

@@ -22,6 +22,7 @@ describe('proxy cookie rewrite helpers', () => {
         expect(shouldProxyCloudPath('/api/taskforce/public/site-config-script')).toBe(true);
         expect(shouldProxyCloudPath('/api/taskforce/version')).toBe(true);
         expect(shouldProxyCloudPath('/api/taskforce/account/entitlements')).toBe(true);
+        expect(shouldProxyCloudPath('/api/taskforce/account/team-management-access')).toBe(true);
         expect(shouldProxyCloudPath('/api/taskforce/admin/mcp-audit-logs')).toBe(true);
         expect(shouldProxyCloudPath('/api/taskforce/billing/status')).toBe(true);
         expect(shouldProxyCloudPath('/api/taskforce/billing/checkout-session')).toBe(true);