@taskforcehq/taskforce 0.3.327 → 0.3.328

package/dist/mcp/taskAttachmentCommandAdapter.d.ts

@@ -52,6 +52,7 @@ export interface SaveTaskAttachmentInput {
     sizeBytes?: unknown;
     expectedSizeBytes?: unknown;
     expectedSha256?: unknown;
+    displayName?: unknown;
     caption?: unknown;
     overwrite?: unknown;
     overwriteAssetId?: unknown;
@@ -69,6 +70,7 @@ export type SaveTaskAttachmentResult = {
     expiresAt: string;
     uploadUrl: string;
     uploadedPath: string;
+    displayName?: string;
     caption?: string;
     overwrite: boolean;
     expectedSizeBytes?: unknown;

package/dist/mcp/taskAttachmentCommandAdapter.js

@@ -20,7 +20,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
     return {
         buildAttachmentResponse,
         async save(input) {
-            const { id: inputId, filename, content, sourcePath, uploadedPath, uploadDraftId, mimeType, sizeBytes, expectedSizeBytes, expectedSha256, caption, overwrite = false, overwriteAssetId, } = input;
+            const { id: inputId, filename, content, sourcePath, uploadedPath, uploadDraftId, mimeType, sizeBytes, expectedSizeBytes, expectedSha256, displayName, caption, overwrite = false, overwriteAssetId, } = input;
             const { id, task } = deps.resolveTask(inputId);
             const durableAttachmentLinksEnabled = deps.durableAttachmentLinksEnabled(id);
             if (!filename || typeof filename !== 'string')
@@ -38,6 +38,9 @@ export function createTaskAttachmentCommandAdapter(deps) {
                 ? caption.trim()
                 : undefined;
             const safeFilename = deps.sanitizeFilename(filename);
+            const safeDisplayName = typeof displayName === 'string' && displayName.trim().length > 0
+                ? displayName.trim()
+                : safeFilename;
             const stableAttachmentAssetId = deps.stableRequestId('operation', `task-attachment-asset:${id}:${safeFilename}`)?.replace(/^operation-/, 'asset-') || `asset-${randomUUID().replace(/-/g, '')}`;
             const safeMimeType = typeof mimeType === 'string' && mimeType.trim().length > 0
                 ? mimeType.trim().toLowerCase()
@@ -53,7 +56,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
                 const overwriteTitle = overwriteTarget
                     ? deps.workspaceAssetStore?.getDocument?.(overwriteTarget.asset.assetId, deps.activeWorkspaceId)?.title
                     : null;
-                const canonicalName = safeCaption || overwriteTitle || safeFilename;
+                const canonicalName = safeCaption || overwriteTitle || overwriteTarget?.asset.logicalName || safeFilename;
                 const persistedCaption = isMarkdownDocument
                     ? canonicalName
                     : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
@@ -63,7 +66,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
                         : `/api/taskforce/context/${encodeURIComponent(storageKey)}`),
                     fsPath: asset?.storageKey || overwriteTarget?.attachment.fsPath || storageKey,
                     caption: isMarkdownDocument ? canonicalName : persistedCaption,
-                    displayName: isMarkdownDocument ? canonicalName : safeFilename,
+                    displayName: safeDisplayName,
                     originalFilename: safeFilename,
                     ...(asset?.assetId ? { assetId: asset.assetId } : {}),
                     timestamp: now,
@@ -110,6 +113,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
                     expiresAt,
                     uploadUrl: objectStorageClient.createSignedPutUrl(stagedAsset.relativePath, uploadExpiresInSeconds, safeMimeType),
                     uploadedPath: stagedAsset.relativePath,
+                    ...(safeDisplayName !== safeFilename ? { displayName: safeDisplayName } : {}),
                     ...(safeCaption ? { caption: safeCaption } : {}),
                     overwrite: overwrite === true,
                     ...(expectedSizeBytes !== undefined ? { expectedSizeBytes } : {}),
@@ -218,7 +222,8 @@ export function createTaskAttachmentCommandAdapter(deps) {
                 const overwriteTitle = overwriteTarget
                     ? deps.workspaceAssetStore?.getDocument?.(overwriteTarget.asset.assetId, deps.activeWorkspaceId)?.title
                     : null;
-                const canonicalName = safeCaption || overwriteTitle || safeFilename;
+                const canonicalName = safeCaption || overwriteTitle || overwriteTarget?.asset.logicalName
+                    || existingUploadedAsset?.logicalName || safeFilename;
                 const persistedCaption = isMarkdownDocument
                     ? canonicalName
                     : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
@@ -234,7 +239,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
                     assetId: overwriteTarget?.asset.assetId || existingUploadedAsset?.assetId || embeddedAssetId || `asset-${randomUUID().replace(/-/g, '')}`,
                     workspaceId: deps.activeWorkspaceId,
                     kind,
-                    logicalName: isMarkdownDocument ? canonicalName : safeFilename,
+                    logicalName: canonicalName,
                     originalFilename: safeFilename,
                     mimeType: resolvedMimeType,
                     storageProvider: 'r2',
@@ -269,7 +274,7 @@ export function createTaskAttachmentCommandAdapter(deps) {
                         assetId: asset.assetId,
                         taskId: id,
                         role: 'attachment',
-                        displayName: kind === 'document' ? null : persistedCaption,
+                        displayName: kind === 'document' ? null : safeDisplayName,
                         updatedAt: now,
                         deletedAt: null,
                     });
@@ -324,13 +329,14 @@ export function createTaskAttachmentCommandAdapter(deps) {
                 const overwriteTitle = overwriteTarget
                     ? deps.workspaceAssetStore?.getDocument?.(overwriteTarget.asset.assetId, deps.activeWorkspaceId)?.title
                     : null;
-                const canonicalName = safeCaption || overwriteTitle || safeFilename;
+                const canonicalName = safeCaption || overwriteTitle || overwriteTarget?.asset.logicalName || safeFilename;
                 const persistedCaption = isMarkdownDocument
                     ? canonicalName
                     : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
                 asset = await deps.canonicalAssetHelpers.ensureCanonicalTaskAttachment(relativePath, id, persistedCaption, now, 'attachment', {
                     originalFilename: safeFilename,
-                    logicalName: isMarkdownDocument ? canonicalName : safeFilename,
+                    logicalName: canonicalName,
+                    displayName: safeDisplayName,
                     ...(!overwriteTarget ? { assetId: stableAttachmentAssetId } : {}),
                     ...(overwriteTarget
                         ? {

package/dist/mcp/taskPlanningRegistrar.js

@@ -112,14 +112,14 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('list_tasks', (context) => ({
-        description: context.describeTool('List active tasks with optional filters, including workstreamId (an ID or WS-123 reference). Use offset and limit for bounded pagination. Use openOnly=true to exclude done/cancelled. Use format=json for programmatic use. Returns compact task summaries without descriptions, comments, activity, attachments, or event streams. When a task URL is provided, preserve it when presenting the task so the user can open it directly. Use get_task for one task’s details.'),
+        description: context.describeTool('List active tasks with filters and bounded pagination. Use workstreamId with an ID or WS-123 and openOnly=true to exclude done/cancelled. Use format=json for programmatic use. Returns compact summaries; use get_task for details. When a task URL is returned, preserve it when presenting the task.'),
         inputSchema: {
             properties: {
                 format: stringProperty('Toggle output format (default: markdown).', ['markdown', 'json']),
                 category: stringProperty('Filter by category.'),
                 status: stringProperty('Filter by status.', ['task', 'on-hold', 'in-progress', 'review', 'done', 'cancelled']),
                 openOnly: booleanProperty('When true, only include open tasks (task, on-hold, in-progress, review).'),
-                assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
+                assignee: stringProperty(context.assigneeHint),
                 priority: numberProperty('Filter by priority level.'),
                 type: stringProperty('Filter by task type.', context.typeEnum),
                 workstreamId: stringProperty('Filter by workstream ID or workstream reference such as WS-123.'),
@@ -131,7 +131,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('search_tasks', (context) => ({
-        description: context.describeTool('Search active and archived tasks by keyword or exact task reference. Matches title, description, internal ID, canonical T-* references, and provisional local LT-* references. Results use linked task references when an application URL is available; preserve those links when presenting tasks. Use scope=\'active\' or scope=\'archive\' to narrow results. Prefer this over list_tasks when looking for a specific task by name.'),
+        description: context.describeTool('Search active and archived tasks by keyword, ID, T-* reference, or provisional LT-* reference. Use scope to narrow results. Prefer this over list_tasks when looking for a specific task by name. When results include links, preserve those links when presenting tasks.'),
         inputSchema: {
             properties: {
                 query: stringProperty('Search term or exact task reference such as T-123 or LT-123.'),
@@ -150,6 +150,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
     }));
     register('link_task_relationship', (context) => ({
         description: context.describeTool('Create an idempotent structured relationship between two tasks. blocks(A,B) is the inverse view of depends_on(B,A). Rejects self-links, missing tasks, and dependency/supersession cycles.'),
+        annotations: { idempotentHint: true },
         inputSchema: { properties: {
                 sourceTaskId: stringProperty('Source task ID or reference.'),
                 targetTaskId: stringProperty('Target task ID or reference.'),
@@ -159,6 +160,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
     }));
     register('unlink_task_relationship', (context) => ({
         description: context.describeTool('Idempotently remove a structured task relationship. The relationship is tombstoned so deletion converges across sync.'),
+        annotations: { idempotentHint: true },
         inputSchema: { properties: {
                 sourceTaskId: stringProperty('Source task ID or reference.'),
                 targetTaskId: stringProperty('Target task ID or reference.'),
@@ -167,11 +169,11 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
             }, required: ['sourceTaskId', 'targetTaskId', 'type'] },
     }));
     register('get_task', (context) => ({
-        description: context.describeTool('Get one task by ID or T-123 reference. The default compact response returns scalar task fields and collection counts without comments, history, checklist items, or attachments. When the response includes url, preserve it in any task reference you present so the user can open the task directly. Pass detail=full for comments and attachment/checklist metadata, or detail=history for one chronological comment/event stream. Use get_task_attachments for attachment bodies; use D-123/I-123 tools for documents/images. When showing this task to the user in a client that supports rich inline rendering, prefer a compact visual summary that retains the task link.'),
+        description: context.describeTool('Get one task by ID or T-123 reference. The default compact response returns scalar fields and collection counts. Use detail=full for comments and attachment/checklist metadata, or detail=history for chronology. Use get_task_attachments for attachment bodies; use D-123/I-123 tools for documents/images. When url is returned, preserve it in any task reference you present.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
-                detail: stringProperty('Response detail level (default: compact). Use full for comments and attachment/checklist metadata, or history for chronological task events.', ['compact', 'full', 'history']),
+                detail: stringProperty('Response detail: compact, full, or chronological history.', ['compact', 'full', 'history']),
             },
             required: ['id'],
         },
@@ -185,24 +187,24 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('get_initiative', (context) => ({
-        description: context.describeTool('Get one initiative by ID or IN-123 reference. The default compact response returns summary counts. Use detail=planning for current attachments plus paginated active/archived workstream summaries and historical task counts, detail=history for bounded chronological history, or detail=full for the compatible rich response.'),
+        description: context.describeTool('Get one initiative by ID or IN-123. Compact returns counts; detail=planning adds attachments, paginated workstreams, and historical task counts; detail=history returns bounded chronology; full returns the compatible rich response.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
-                detail: stringProperty('Response detail level (default: compact). Planning excludes history; history is chronological and bounded; full preserves the rich response.', ['compact', 'planning', 'history', 'full']),
-                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Page size for planning workstreams or history entries (default: 25, max: 100).' },
-                offset: { type: 'integer', minimum: 0, description: 'Non-negative page offset for planning workstreams or history entries (default: 0).' },
+                detail: stringProperty('Response detail: compact, planning, history, or full.', ['compact', 'planning', 'history', 'full']),
+                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Planning/history page size (default 25; max 100).' },
+                offset: { type: 'integer', minimum: 0, description: 'Planning/history page offset (default 0).' },
             },
             required: ['id'],
         },
     }));
     register('create_initiative', (context) => ({
-        description: context.describeTool('Create a new initiative. Use this for the top planning layer when a body of work should coordinate multiple workstreams.'),
+        description: context.describeTool('Create a new initiative. Pass idempotencyKey when retrying after an ambiguous timeout; reuse it only with the exact same payload.'),
         inputSchema: {
             properties: {
                 title: stringProperty('Initiative title.'),
                 description: stringProperty('Optional initiative description.'),
-                ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
+                ownerId: stringProperty(context.assigneeHint),
                 order: numberProperty('Optional sort order among initiatives.'),
                 attachments: arrayProperty('Optional attachment descriptors to store on the initiative. Prefer save_initiative_attachment for generated content or files.', {
                     type: 'object',
@@ -216,6 +218,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                     },
                     required: ['path'],
                 }),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Optional opaque retry key scoped to the active workspace, actor, and tool.' },
             },
             required: ['title'],
         },
@@ -227,9 +230,9 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
                 title: stringProperty('Updated initiative title.'),
                 description: stringProperty('Updated initiative description.'),
-                ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
+                ownerId: stringProperty(context.assigneeHint),
                 order: numberProperty('Optional sort order among initiatives.'),
-                attachments: arrayProperty('Replacement attachment descriptors for the initiative. Prefer save_initiative_attachment and delete_initiative_attachment for generated content or files.', {
+                attachments: arrayProperty('Replacement attachment descriptors for the initiative. Prefer save_initiative_attachment for generated content or files. Removing managed attachments requires delete_initiative_attachment in the extended profile.', {
                     type: 'object',
                     properties: {
                         path: { type: 'string' },
@@ -246,11 +249,12 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('add_initiative_comment', (context) => ({
-        description: context.describeTool('Add a comment to an initiative. Use this for initiative-level progress notes, decisions, coordination context, and audit trails. Comments appear in the initiative activity feed.'),
+        description: context.describeTool('Add a comment to an initiative. Pass idempotencyKey when retrying after an ambiguous timeout; reuse it only with the exact same target and text.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
                 text: stringProperty('Comment text.'),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Optional opaque retry key scoped to the active workspace, actor, and tool.' },
             },
             required: ['id', 'text'],
         },
@@ -282,24 +286,24 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('get_workstream', (context) => ({
-        description: context.describeTool('Get one workstream by ID or WS-123 reference. The default compact response returns a summary and task count. Use detail=planning for current attachments and explicit historical task counts without nested tasks, detail=history for bounded chronological history, or detail=full for the compatible rich response. Use list_tasks with workstreamId for bounded active task discovery.'),
+        description: context.describeTool('Get one workstream by ID or WS-123. Compact returns a summary and task count; detail=planning adds attachments and historical counts; detail=history returns bounded chronology; full returns the compatible rich response. Use list_tasks with workstreamId for active tasks.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
-                detail: stringProperty('Response detail level (default: compact). Planning excludes history and nested tasks; history is chronological and bounded; full preserves the rich response.', ['compact', 'planning', 'history', 'full']),
-                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Page size for history entries (default: 25, max: 100).' },
-                offset: { type: 'integer', minimum: 0, description: 'Non-negative history page offset (default: 0).' },
+                detail: stringProperty('Response detail: compact, planning, history, or full.', ['compact', 'planning', 'history', 'full']),
+                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'History page size (default 25; max 100).' },
+                offset: { type: 'integer', minimum: 0, description: 'History page offset (default 0).' },
             },
             required: ['id'],
         },
     }));
     register('create_workstream', (context) => ({
-        description: context.describeTool('Create a new workstream. Use initiativeId to link it to an initiative, or omit initiativeId to create a standalone workstream.'),
+        description: context.describeTool('Create a new workstream. Pass idempotencyKey when retrying after an ambiguous timeout; reuse it only with the exact same payload.'),
         inputSchema: {
             properties: {
                 title: stringProperty('Workstream title.'),
                 description: stringProperty('Optional workstream description.'),
-                ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
+                ownerId: stringProperty(context.assigneeHint),
                 initiativeId: stringProperty('Optional initiative ID or initiative reference such as IN-123.'),
                 order: numberProperty('Optional sort order among workstreams.'),
                 attachments: arrayProperty('Optional attachment descriptors to store on the workstream. Prefer save_workstream_attachment for generated content or files.', {
@@ -314,6 +318,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                     },
                     required: ['path'],
                 }),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Optional opaque retry key scoped to the active workspace, actor, and tool.' },
             },
             required: ['title'],
         },
@@ -325,10 +330,10 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
                 title: stringProperty('Updated workstream title.'),
                 description: stringProperty('Updated workstream description.'),
-                ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
+                ownerId: stringProperty(context.assigneeHint),
                 initiativeId: stringProperty('Optional initiative ID or initiative reference such as IN-123. Pass an empty string to unlink.'),
                 order: numberProperty('Optional sort order among workstreams.'),
-                attachments: arrayProperty('Replacement attachment descriptors for the workstream. Prefer save_workstream_attachment and delete_workstream_attachment for generated content or files.', {
+                attachments: arrayProperty('Replacement attachment descriptors for the workstream. Prefer save_workstream_attachment for generated content or files. Removing managed attachments requires delete_workstream_attachment in the extended profile.', {
                     type: 'object',
                     properties: {
                         path: { type: 'string' },
@@ -345,11 +350,12 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('add_workstream_comment', (context) => ({
-        description: context.describeTool('Add a comment to a workstream. Use this for workstream-level progress notes, decisions, coordination context, and audit trails. Comments appear in the workstream activity feed.'),
+        description: context.describeTool('Add a comment to a workstream. Pass idempotencyKey when retrying after an ambiguous timeout; reuse it only with the exact same target and text.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
                 text: stringProperty('Comment text.'),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Optional opaque retry key scoped to the active workspace, actor, and tool.' },
             },
             required: ['id', 'text'],
         },
@@ -374,6 +380,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
     }));
     register('update_task_workstream', (context) => ({
         description: context.describeTool('Set or clear the workstream for one task. Pass workstreamId to assign or reassign; pass an empty string or null to unlink the task from its current workstream.'),
+        annotations: { idempotentHint: true },
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),
@@ -447,13 +454,13 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),
-                id: stringProperty('Alias for taskId. Task ID or task reference such as T-123.'),
-                date: nullableStringProperty('Target date in YYYY-MM-DD format. Pass an empty string or null with taskId to unschedule.'),
-                scheduledDate: nullableStringProperty('Alias for date. Target date in YYYY-MM-DD format. Pass an empty string or null with taskId to unschedule.'),
+                id: stringProperty('Alias for taskId.'),
+                date: nullableStringProperty('YYYY-MM-DD; null or empty with taskId unschedules.'),
+                scheduledDate: nullableStringProperty('Alias for date.'),
                 order: numberProperty('Optional position within that day.'),
-                orderInDay: numberProperty('Alias for order. Optional position within that day.'),
-                taskIds: arrayProperty('Ordered task IDs or task references for replacing one scheduled day order.', { type: 'string' }),
-                moves: arrayProperty('Advanced reorder moves. Each move may include id or taskId, date or scheduledDate, and order or orderInDay.', {
+                orderInDay: numberProperty('Alias for order.'),
+                taskIds: arrayProperty('Ordered task IDs or references replacing one day.', { type: 'string' }),
+                moves: arrayProperty('Advanced reorder moves using task, date, and order aliases.', {
                     type: 'object',
                     properties: {
                         id: { type: 'string' },
@@ -513,7 +520,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('create_task', (context) => ({
-        description: context.describeTool('Create a new task. Pass idempotencyKey when the call may be retried after a timeout; the same key and payload return the original task, while a changed payload is rejected. Current taxonomy values are included in this schema; call get_config only for richer metadata or after a validation mismatch.'),
+        description: context.describeTool('Create a task. For retries, the same idempotencyKey and payload return the original; changed payloads conflict. Taxonomy enums are current; use get_config for metadata or after validation errors.'),
         inputSchema: {
             properties: {
                 title: stringProperty('Task title.'),
@@ -524,8 +531,8 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                     description: 'Optional opaque retry key scoped to the active workspace and AI profile.',
                 },
                 description: stringProperty('Optional task description.'),
-                assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
-                workstreamId: stringProperty('Optional workstream ID or workstream reference such as WS-123. Use this to create the task directly inside a workstream without a separate update_task_workstream call. Call list_workstreams with query first if you only know the workstream name.'),
+                assignee: stringProperty(context.assigneeHint),
+                workstreamId: stringProperty('Workstream ID or WS-123; use to create the task directly inside a workstream. Search list_workstreams if needed.'),
                 category: stringProperty('Task category value.', context.categoryEnum),
                 type: stringProperty('Task type value.', context.typeEnum),
                 priority: numberProperty(context.priorityDesc),
@@ -548,6 +555,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
     }));
     register('reopen_task', (context) => ({
         description: context.describeTool('Safely resume reviewed work in one call. Reopens archived done tasks or active/archived review tasks to in-progress, preserves an existing assignee, and claims only unassigned work. Cancelled tasks are rejected. Already in-progress tasks are idempotent no-ops.'),
+        annotations: { idempotentHint: true },
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
@@ -562,7 +570,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                 id: stringProperty('Task ID or task reference such as T-123.'),
                 title: stringProperty('Updated task title.'),
                 description: stringProperty('Updated task description.'),
-                assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
+                assignee: stringProperty(context.assigneeHint),
                 workstreamId: stringProperty('Updated workstream ID or workstream reference such as WS-123. Pass an empty string to unlink the task. Call list_workstreams with query first if you only know the workstream name.'),
                 category: stringProperty('Updated category value.', context.categoryEnum),
                 type: stringProperty('Updated task type value.', context.typeEnum),
@@ -576,7 +584,7 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('finish_task', (context) => ({
-        description: context.describeTool('default end-of-task handoff for active work. Archived tasks are rejected; call reopen_task first. Use outcome=\'done\' when work is complete and outcome=\'review\' when human validation or approval is needed. If you report completed work on a tracked task, either finish it with this tool or explain why it remains open. Both outcomes remain active and unarchived. This tool never archives automatically; use archive_task separately to move work to history. The response always reports completion.archived from persisted state.'),
+        description: context.describeTool('Default end-of-task handoff. Use outcome=\'done\' for completed work or outcome=\'review\' for validation. Both remain active and unarchived; use archive_task for history. Archived tasks require reopen_task first.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),

package/dist/mcp/toolRegistry.js

@@ -52,10 +52,10 @@ export const MCP_TOOL_REGISTRY = Object.freeze({
     replace_task_checklist: defaultTool({ kind: 'scope', scope: 'tasks:write' }, true),
     get_task_attachments: defaultTool({ kind: 'scope', scope: 'tasks:read' }, false),
     get_workstream_attachments: extendedTool({ kind: 'scope', scope: 'tasks:read' }, false),
-    save_workstream_attachment: extendedTool({ kind: 'scope', scope: 'tasks:write' }, true),
+    save_workstream_attachment: defaultTool({ kind: 'scope', scope: 'tasks:write' }, true),
     delete_workstream_attachment: extendedTool({ kind: 'scope', scope: 'tasks:write' }, true),
     get_initiative_attachments: extendedTool({ kind: 'scope', scope: 'tasks:read' }, false),
-    save_initiative_attachment: extendedTool({ kind: 'scope', scope: 'tasks:write' }, true),
+    save_initiative_attachment: defaultTool({ kind: 'scope', scope: 'tasks:write' }, true),
     delete_initiative_attachment: extendedTool({ kind: 'scope', scope: 'tasks:write' }, true),
     search_images: defaultTool({ kind: 'scope', scope: 'tasks:read' }, false),
     get_image: defaultTool({ kind: 'scope', scope: 'tasks:read' }, false),

package/dist/migrations/taskSchemaMigrations.js

@@ -1160,6 +1160,22 @@ export function ensureWorkspaceAssetsSchema(db) {
         ON workspace_asset_links(tenant_id, workspace_id, asset_id, deleted_at, updated_at);
         CREATE INDEX IF NOT EXISTS idx_workspace_asset_links_workspace_updated
         ON workspace_asset_links(tenant_id, workspace_id, updated_at, asset_id);
+
+        CREATE TABLE IF NOT EXISTS workspace_asset_upload_drafts (
+            tenant_id TEXT NOT NULL DEFAULT 'default',
+            workspace_id TEXT NOT NULL,
+            draft_id TEXT NOT NULL,
+            asset_id TEXT NOT NULL,
+            storage_key TEXT NOT NULL,
+            purpose TEXT NOT NULL,
+            created_by_user_id TEXT NOT NULL,
+            created_at TEXT NOT NULL,
+            retired_at TEXT,
+            PRIMARY KEY (tenant_id, workspace_id, draft_id, asset_id)
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_workspace_asset_upload_drafts_expiry
+        ON workspace_asset_upload_drafts(tenant_id, workspace_id, retired_at, created_at);
     `);
     const linkColumns = db.prepare(`PRAGMA table_info(workspace_asset_links)`).all();
     const hasDisplayNameColumn = linkColumns.some((c) => c.name === 'display_name');
@@ -2801,6 +2817,9 @@ export function ensureDocumentReviewSessionsSchema(db) {
             thread_status_updated_at TEXT,
             resolved_at TEXT,
             resolved_by_actor_id TEXT,
+            idempotency_key TEXT,
+            idempotency_fingerprint TEXT,
+            idempotency_actor_scope TEXT NOT NULL DEFAULT '',
             order_index INTEGER NOT NULL DEFAULT 0,
             created_at TEXT NOT NULL,
             updated_at TEXT NOT NULL,
@@ -2830,6 +2849,22 @@ export function ensureDocumentReviewSessionsSchema(db) {
     if (!commentColumnNames.has('deleted_by_actor_id')) {
         addCommentColumn('deleted_by_actor_id');
     }
+    if (!commentColumnNames.has('idempotency_key')) {
+        addCommentColumn('idempotency_key');
+    }
+    if (!commentColumnNames.has('idempotency_fingerprint')) {
+        addCommentColumn('idempotency_fingerprint');
+    }
+    if (!commentColumnNames.has('idempotency_actor_scope')) {
+        const ifNotExists = db.provider === 'postgres' ? ' IF NOT EXISTS' : '';
+        db.exec(`ALTER TABLE document_review_comments ADD COLUMN${ifNotExists} idempotency_actor_scope TEXT NOT NULL DEFAULT ''`);
+    }
+    db.exec(`
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_document_review_comments_idempotency
+        ON document_review_comments (
+            tenant_id, workspace_id, idempotency_actor_scope, idempotency_key
+        )
+    `);
     if (!commentColumnNames.has('parent_comment_id')) {
         addCommentColumn('parent_comment_id');
     }

package/dist/runtime/appGateDefinitions.d.ts

@@ -12,13 +12,13 @@ export declare const APP_GATE_DEFINITIONS: {
         readonly removalMilestone: "Document Manager GA";
     };
     readonly 'workflow_manager.workspace_access': {
-        readonly enabled: true;
+        readonly enabled: false;
         readonly description: "Workflow Manager workspace readiness gate.";
         readonly owner: "taskforce";
         readonly removalMilestone: "Workflow Manager GA";
     };
     readonly 'taskforce_agents.workspace_access': {
-        readonly enabled: true;
+        readonly enabled: false;
         readonly description: "Taskforce Agents workspace readiness gate.";
         readonly owner: "taskforce";
         readonly removalMilestone: "Taskforce Agents workspace GA";

package/dist/runtime/appGateDefinitions.js

@@ -12,13 +12,13 @@ export const APP_GATE_DEFINITIONS = {
         removalMilestone: 'Document Manager GA'
     },
     'workflow_manager.workspace_access': {
-        enabled: true,
+        enabled: false,
         description: 'Workflow Manager workspace readiness gate.',
         owner: 'taskforce',
         removalMilestone: 'Workflow Manager GA'
     },
     'taskforce_agents.workspace_access': {
-        enabled: true,
+        enabled: false,
         description: 'Taskforce Agents workspace readiness gate.',
         owner: 'taskforce',
         removalMilestone: 'Taskforce Agents workspace GA'

package/dist/server/appAccess.d.ts

@@ -0,0 +1,12 @@
+import type { AccountAccessStatus } from '../core/types.js';
+export interface AppAccessDeniedResponse {
+    statusCode: 403;
+    body: {
+        error: string;
+        code: string;
+        gate: AccountAccessStatus['gate'];
+        canAccessPlans: boolean;
+        planSelectionRequired: boolean;
+    };
+}
+export declare function resolveAppAccessDeniedResponse(accountAccess: AccountAccessStatus): AppAccessDeniedResponse | null;

package/dist/server/appAccess.js

@@ -0,0 +1,21 @@
+export function resolveAppAccessDeniedResponse(accountAccess) {
+    if (accountAccess.canAccessApp)
+        return null;
+    const code = accountAccess.gate === 'plan_selection_required'
+        ? 'PLAN_SELECTION_REQUIRED'
+        : accountAccess.gate === 'checkout_pending'
+            ? 'CHECKOUT_PENDING'
+            : accountAccess.gate === 'misconfigured'
+                ? 'ACCOUNT_ACCESS_MISCONFIGURED'
+                : 'ACCOUNT_ENTITLEMENT_REQUIRED';
+    return {
+        statusCode: 403,
+        body: {
+            error: accountAccess.message || 'This account cannot access the app.',
+            code,
+            gate: accountAccess.gate,
+            canAccessPlans: accountAccess.canAccessPlans,
+            planSelectionRequired: accountAccess.planSelectionRequired
+        }
+    };
+}

package/dist/server/authorizedWorkspaceAccess.d.ts

@@ -0,0 +1,12 @@
+import type { TaskforceCore } from '../core/Taskforce.js';
+import type { RequestAccessContext } from './auth.js';
+export interface AuthorizedRequestAccess extends RequestAccessContext {
+    disabled?: boolean;
+    accountDisabled?: boolean;
+    workspaceDisabled?: boolean;
+}
+type WorkspaceAccessCore = Pick<TaskforceCore, 'resolveUserAccess' | 'getSystemRole'>;
+export declare function resolveAuthorizedWorkspaceAccess(core: WorkspaceAccessCore, access: AuthorizedRequestAccess, requestedWorkspaceId: string): AuthorizedRequestAccess;
+export declare function isWorkspaceAccessRecoveryRoute(pathname: string): boolean;
+export declare function resolveDisabledAccessError(access: Pick<AuthorizedRequestAccess, 'disabled' | 'accountDisabled' | 'workspaceDisabled'>, pathname: string): string | null;
+export {};

package/dist/server/authorizedWorkspaceAccess.js

@@ -0,0 +1,40 @@
+export function resolveAuthorizedWorkspaceAccess(core, access, requestedWorkspaceId) {
+    if (!access.authenticated || !access.userId || access.userId === 'anonymous')
+        return access;
+    const trimmedRequestedWorkspaceId = String(requestedWorkspaceId || '').trim();
+    const candidateWorkspaceIds = [
+        trimmedRequestedWorkspaceId,
+        String(access.workspaceId || '').trim()
+    ].filter((workspaceId, index, values) => Boolean(workspaceId) && values.indexOf(workspaceId) === index);
+    for (const workspaceId of candidateWorkspaceIds) {
+        const resolved = core.resolveUserAccess(access.userId, workspaceId, access.role);
+        if (!resolved)
+            continue;
+        return {
+            ...access,
+            role: resolved.role,
+            workspaceId: resolved.workspaceId,
+            userId: resolved.userId,
+            systemRole: core.getSystemRole(resolved.userId),
+            disabled: resolved.disabled,
+            accountDisabled: resolved.accountDisabled ?? resolved.disabled,
+            workspaceDisabled: resolved.workspaceDisabled ?? false
+        };
+    }
+    return access;
+}
+export function isWorkspaceAccessRecoveryRoute(pathname) {
+    return pathname === '/api/taskforce/workspaces'
+        || pathname === '/api/taskforce/session/workspace';
+}
+export function resolveDisabledAccessError(access, pathname) {
+    if (pathname.startsWith('/api/taskforce/auth/'))
+        return null;
+    if (access.accountDisabled ?? access.disabled) {
+        return 'Forbidden: user account is disabled.';
+    }
+    if (access.workspaceDisabled && !isWorkspaceAccessRecoveryRoute(pathname)) {
+        return 'Forbidden: workspace access is not active for this user.';
+    }
+    return null;
+}

package/dist/server/cloudCollectionRead.d.ts

@@ -0,0 +1,25 @@
+import type { TaskforceCore } from '../core/Taskforce.js';
+import { type AuthorizedRequestAccess } from './authorizedWorkspaceAccess.js';
+export type CloudCollectionReadOperation = 'tasks' | 'archive' | 'deleted' | 'planning-bootstrap';
+export interface CloudCollectionReadRequest {
+    operation: CloudCollectionReadOperation;
+    pathname: string;
+    requestedWorkspaceId: string;
+    access: AuthorizedRequestAccess;
+    performanceTrace: boolean;
+}
+export interface CloudCollectionReadResponse {
+    statusCode: number;
+    headers: Record<string, string>;
+    body: string;
+    workspaceId: string;
+    performance?: {
+        durationMs: number;
+        details: Record<string, number>;
+    };
+}
+type CloudCollectionReadCore = Pick<TaskforceCore, 'resolveUserAccess' | 'getSystemRole' | 'getAccountAccessStatus' | 'listTasks' | 'listArchive' | 'listDeletedTasksReadOnly' | 'listPlanningBootstrap'>;
+export declare function resolveCloudCollectionReadOperation(method: string | undefined, pathname: string): CloudCollectionReadOperation | null;
+export declare function executeCloudCollectionRead(core: CloudCollectionReadCore, request: CloudCollectionReadRequest): CloudCollectionReadResponse;
+export declare function cloudCollectionReadRoute(operation: CloudCollectionReadOperation): string;
+export {};