@taskforcehq/taskforce 0.3.327 → 0.3.329

package/dist/server/routes/agents.js

@@ -11,10 +11,12 @@
  *   POST   /api/taskforce/agents/model-gateway/test
  *   PATCH  /api/taskforce/agents/:agentId/conversations/:conversationId
  */
+import { createHash } from 'node:crypto';
 import { assignedAiProfileColor, normalizeAiProfileColor } from '../../shared/aiProfileColors.js';
 import { BedrockAnthropicMessagesModelGateway } from '../../services/bedrockAnthropicMessagesModelGateway.js';
 import { BedrockMantleModelGateway } from '../../services/bedrockMantleModelGateway.js';
 import { BedrockModelGateway } from '../../services/bedrockModelGateway.js';
+import { CodexAppServerModelGateway } from '../../services/codexAppServerModelGateway.js';
 import { saveAiProfileAvatarAssets } from '../aiProfileAvatarAssets.js';
 import { ModelGatewayConfigurationError, normalizePersistedModelGatewayMessages } from '../../services/modelGateway.js';
 import { BedrockAvatarImageProvider, buildTaskforceAgentAvatarPrompt, } from '../../services/taskforceAgentAvatarImageProvider.js';
@@ -25,10 +27,11 @@ import { TaskforceAgentSkillStore } from '../../storage/taskforceAgentSkillStore
 import { WorkflowStore } from '../../storage/workflowStore.js';
 import { WorkspaceSyncDurabilityStore } from '../../sync/v3/syncDurabilityStore.js';
 import { projectLegacyTaskforceAgentResponse } from '../../compat/taskforceAgentDefinitionCompat.js';
-import { TASKFORCE_AGENTS_WORKSPACE_FEATURE_KEY, resolveAppGateAccess, } from '../../runtime/appGates.js';
+import { TASKFORCE_AGENTS_WORKSPACE_FEATURE_KEY, } from '../../runtime/appGates.js';
+import { resolveNodeAppGateAccess } from '../../runtime/nodeAppGates.js';
 import { DEFAULT_TASKFORCE_AGENT_MODEL_KEY, DEFAULT_TASKFORCE_AGENT_PROVIDER_KEY, getTaskforceAgentModel, isTaskforceAgentModelVisible, labelForTaskforceAgentModel, labelForTaskforceAgentProvider, normalizeTaskforceAgentModelKey, normalizeTaskforceAgentModelSelection, normalizeTaskforceAgentProviderKey, } from '../../shared/taskforceAgentModels.js';
 import { buildTaskforceAgentRunContext } from '../../shared/taskforceAgentRunContext.js';
-import { inspectAgentDefinition } from '../../shared/taskforceAgentDefinition.js';
+import { inspectAgentDefinition, serializeCanonicalJson } from '../../shared/taskforceAgentDefinition.js';
 import { buildResolvedTaskforceAgentSystemPrompt, resolveTaskforceAgentRuntimeConfiguration, TaskforceAgentRuntimeResolutionError, } from '../../shared/taskforceAgentRuntimeResolution.js';
 import { serializeTaskforceAgentExecutionSnapshot } from '../../shared/taskforceAgentExecutionSnapshot.js';
 import { getTaskReferenceLabel } from '../../utils/taskReferences.js';
@@ -113,6 +116,11 @@ function normalizeMessages(value, fallbackPrompt) {
         return { error: 'Prompt must be 4,000 characters or less.' };
     return { messages: [{ role: 'user', content: prompt }] };
 }
+function buildManagedAgentExecutionRequestId(input) {
+    return createHash('sha256')
+        .update(serializeCanonicalJson(input))
+        .digest('hex');
+}
 function toGatewayMessages(messages) {
     return messages.map((message) => ({
         role: message.role,
@@ -122,7 +130,13 @@ function toGatewayMessages(messages) {
 function requestsWorkflowStepCompletion(messages) {
     const latestUserMessage = [...messages].reverse().find((message) => message.role === 'user');
     const content = String(latestUserMessage?.content || '').trim().toLowerCase();
-    return /^(?:please\s+|(?:can|could|would)\s+you\s+)?(?:perform\s+and\s+complete|complete|finish)\s+(?:your|the|this)\s+(?:current\s+)?workflow\s+step[.!?]*$/.test(content);
+    return /^(?:(?:hey|hi|hello)\b[^,!?]{0,80},?\s+)?(?:please\s+|(?:can|could|would)\s+you\s+)?(?:perform\s+and\s+complete|complete|finish)\s+(?:your|the|this)\s+(?:current\s+)?workflow\s+step(?:\s+(?:on|for)\s+(?:task\s+)?(?:t-\d+|[a-z0-9][a-z0-9-]{0,119}))?[.!?]*$/.test(content);
+}
+function extractLatestExplicitTaskReference(messages) {
+    const latestUserMessage = [...messages].reverse().find((message) => message.role === 'user');
+    const matches = String(latestUserMessage?.content || '').match(/\bT-\d+\b/gi) || [];
+    const references = [...new Set(matches.map((match) => match.toUpperCase()))];
+    return references.length === 1 ? references[0] : null;
 }
 function normalizeTaskId(value) {
     const taskId = String(value || '').trim();
@@ -144,6 +158,18 @@ function resolveTaskContextTask(core, workspaceId, taskId) {
     return core.getTask(taskId, workspaceId)
         || (typeof core.resolveTaskIdentifier === 'function' ? core.resolveTaskIdentifier(taskId, workspaceId) : null);
 }
+function workflowToolCallsTargetSameTask(core, workspaceId, left, right) {
+    const resolveCanonicalId = (value) => {
+        const taskId = normalizeTaskId(value);
+        if (!taskId)
+            return null;
+        const task = resolveTaskContextTask(core, workspaceId, taskId);
+        return normalizeTaskId(task?.id)?.toLowerCase() || taskId.toLowerCase();
+    };
+    const leftTaskId = resolveCanonicalId(left);
+    const rightTaskId = resolveCanonicalId(right);
+    return Boolean(leftTaskId && rightTaskId && leftTaskId === rightTaskId);
+}
 function resolveTaskScopeContext(core, workspaceId, input) {
     const taskId = String(input.taskId || '').trim();
     if (!taskId)
@@ -244,6 +270,12 @@ function createDefaultModelGateway(selection) {
     }
     const source = selection?.modelSource || model?.source || 'bedrock';
     const runtime = selection?.runtime || model?.runtime || 'bedrock-runtime';
+    if (source === 'subscription_dev' && runtime === 'subscription-dev') {
+        if (selection?.connectionScope !== 'local_dev') {
+            throw new ModelGatewayConfigurationError('Subscription-dev models require local_dev connection scope.', 'MODEL_SOURCE_UNAVAILABLE');
+        }
+        return new CodexAppServerModelGateway();
+    }
     if (source !== 'bedrock') {
         throw new ModelGatewayConfigurationError('Selected model source is not configured yet.', 'MODEL_SOURCE_NOT_IMPLEMENTED');
     }
@@ -693,7 +725,7 @@ export function registerAgentsRoutes(deps) {
     const ensureTaskforceAgentsAccess = (req, res) => {
         if (!ensureAppAccess(req, res))
             return false;
-        const gate = resolveAppGateAccess(TASKFORCE_AGENTS_WORKSPACE_FEATURE_KEY);
+        const gate = resolveNodeAppGateAccess(TASKFORCE_AGENTS_WORKSPACE_FEATURE_KEY);
         if (gate.allowed)
             return true;
         writeJson(res, 403, {
@@ -1149,9 +1181,30 @@ export function registerAgentsRoutes(deps) {
                 }
             }
             const savedConversationTaskId = savedConversation?.taskId ? normalizeTaskId(savedConversation.taskId) : null;
-            const taskId = hasTaskId ? bodyTaskId : savedConversationTaskId;
-            const taskReference = taskId ? normalizeTaskContextValue(body?.taskReference) : '';
-            const taskTitle = taskId ? normalizeTaskContextValue(body?.taskTitle) : '';
+            const explicitTaskReference = extractLatestExplicitTaskReference(normalizedMessages.messages);
+            const explicitTask = explicitTaskReference
+                ? resolveTaskContextTask(core, workspaceId, explicitTaskReference)
+                : null;
+            if (explicitTaskReference
+                && !explicitTask
+                && requestsWorkflowStepCompletion(normalizedMessages.messages)) {
+                writeJson(res, 404, {
+                    success: false,
+                    error: `Task ${explicitTaskReference} was not found.`,
+                    code: 'TASK_NOT_FOUND',
+                });
+                return;
+            }
+            const taskId = normalizeTaskId(explicitTask?.id)
+                || (explicitTaskReference ? null : hasTaskId ? bodyTaskId : savedConversationTaskId);
+            const taskReference = taskId
+                ? normalizeTaskContextValue(getTaskReferenceLabel(explicitTask)
+                    || (explicitTask ? explicitTaskReference : null)
+                    || body?.taskReference)
+                : '';
+            const taskTitle = taskId
+                ? normalizeTaskContextValue(explicitTask?.title || body?.taskTitle)
+                : '';
             if (resolvedRuntimeConfiguration) {
                 const definition = resolvedRuntimeConfiguration.definition;
                 const draftDiffers = ((body?.providerKey !== undefined
@@ -1272,6 +1325,13 @@ export function registerAgentsRoutes(deps) {
                 allowedMutationTaskId: taskId ?? null,
                 readOnly: !savedAgent,
                 toolPolicy: resolvedRuntimeConfiguration?.definition.toolPolicy,
+                executionRequestId: buildManagedAgentExecutionRequestId({
+                    workspaceId,
+                    agentId: savedAgent?.id || agentId || null,
+                    conversationId,
+                    taskId: taskId ?? null,
+                    messages: normalizedMessages.messages,
+                }),
                 system: scopedAgentSystem,
             });
             const executionSnapshot = savedAgent && resolvedRuntimeConfiguration
@@ -1304,21 +1364,40 @@ export function registerAgentsRoutes(deps) {
                 && mcpBridge?.availableToolNames.includes('complete_workflow_step')
                 && requestsWorkflowStepCompletion(gatewayInput.messages));
             let workflowCompletionCorrectionSent = false;
+            let reservedWorkflowCompletionUsed = false;
             while (mcpBridge) {
                 if (requestedToolCall) {
-                    if (mcpToolResults.length >= MAX_MCP_TOOL_ITERATIONS)
+                    const activeToolCall = requestedToolCall;
+                    const workflowStepAlreadyCompleted = mcpToolResults.some((toolResult) => (toolResult.name === 'complete_workflow_step' && toolResult.ok));
+                    const workflowStepLoaded = activeToolCall.name === 'complete_workflow_step'
+                        && mcpToolResults.some((toolResult) => (toolResult.name === 'get_task_workflow'
+                            && toolResult.ok
+                            && workflowToolCallsTargetSameTask(core, workspaceId, toolResult.arguments?.taskId, activeToolCall.arguments?.taskId)));
+                    const canUseReservedWorkflowCompletion = Boolean(workflowCompletionRequested
+                        && !workflowStepAlreadyCompleted
+                        && !reservedWorkflowCompletionUsed
+                        && activeToolCall.name === 'complete_workflow_step'
+                        && workflowStepLoaded
+                        && unresolvedFailedMutations.size === 0);
+                    if (mcpToolResults.length >= MAX_MCP_TOOL_ITERATIONS
+                        && !canUseReservedWorkflowCompletion)
                         break;
-                    const blocksWorkflowCompletion = requestedToolCall.name === 'complete_workflow_step'
-                        && unresolvedFailedMutations.size > 0;
+                    if (mcpToolResults.length >= MAX_MCP_TOOL_ITERATIONS) {
+                        reservedWorkflowCompletionUsed = true;
+                    }
+                    const blocksWorkflowCompletion = activeToolCall.name === 'complete_workflow_step'
+                        && (!workflowStepLoaded || unresolvedFailedMutations.size > 0);
                     const unresolvedMutationNames = [...new Set(unresolvedFailedMutations.values())];
                     const toolResult = blocksWorkflowCompletion
                         ? {
-                            name: requestedToolCall.name,
-                            arguments: requestedToolCall.arguments,
+                            name: activeToolCall.name,
+                            arguments: activeToolCall.arguments,
                             ok: false,
-                            text: `Taskforce refused workflow completion because these earlier changes failed: ${unresolvedMutationNames.join(', ')}. Retry the failed changes successfully before completing the step.`,
+                            text: !workflowStepLoaded
+                                ? 'Taskforce refused workflow completion because the current workflow step was not loaded successfully. Call get_task_workflow first, perform its instructions, then retry completion.'
+                                : `Taskforce refused workflow completion because these earlier changes failed: ${unresolvedMutationNames.join(', ')}. Retry the failed changes successfully before completing the step.`,
                         }
-                        : await mcpBridge.executeToolCall(requestedToolCall);
+                        : await mcpBridge.executeToolCall(activeToolCall);
                     mcpToolResults.push(toolResult);
                     if (isTaskforceAgentMutationToolName(toolResult.name)
                         && toolResult.name !== 'complete_workflow_step') {
@@ -1349,6 +1428,17 @@ export function registerAgentsRoutes(deps) {
                         throw error;
                     }
                     requestedToolCall = mcpBridge.parseToolCall(result.text);
+                    if (toolResult.name === 'complete_workflow_step'
+                        && toolResult.ok
+                        && requestedToolCall
+                        && mcpToolResults.length >= MAX_MCP_TOOL_ITERATIONS) {
+                        result = {
+                            ...result,
+                            text: 'Workflow step completed successfully.',
+                        };
+                        requestedToolCall = null;
+                        break;
+                    }
                     continue;
                 }
                 const workflowStepCompleted = mcpToolResults.some((toolResult) => (toolResult.name === 'complete_workflow_step' && toolResult.ok));
@@ -1358,7 +1448,7 @@ export function registerAgentsRoutes(deps) {
                         role: 'user',
                         content: unresolvedFailedMutations.size > 0
                             ? `The workflow step is not complete because these Taskforce changes failed: ${[...new Set(unresolvedFailedMutations.values())].join(', ')}. Retry those exact changes successfully before calling complete_workflow_step. If they cannot succeed, respond exactly WORKFLOW_STEP_INCOMPLETE: followed by the reason.`
-                            : 'The workflow step is not authoritatively complete. If all required work succeeded, call complete_workflow_step now. Otherwise respond exactly WORKFLOW_STEP_INCOMPLETE: followed by the reason. Do not claim completion without a successful tool result.',
+                            : 'The workflow step is not authoritatively complete. Call get_task_workflow first if it has not succeeded in this response, perform the returned step instructions, then call complete_workflow_step. Otherwise respond exactly WORKFLOW_STEP_INCOMPLETE: followed by the reason. Do not claim completion without successful tool results.',
                     });
                     result = await gateway.generate({
                         ...gatewayInput,
@@ -1370,7 +1460,19 @@ export function registerAgentsRoutes(deps) {
                 break;
             }
             if (requestedToolCall) {
-                throw new Error('Taskforce tool call limit reached before the agent returned a final response.');
+                mcpToolResults.push({
+                    name: requestedToolCall.name,
+                    arguments: requestedToolCall.arguments,
+                    ok: false,
+                    text: 'Taskforce did not execute this call because the per-message tool limit was reached.',
+                });
+                result = {
+                    ...result,
+                    text: workflowCompletionRequested
+                        ? 'WORKFLOW_STEP_INCOMPLETE: Taskforce reached the per-message tool limit before finishing the workflow step. Review Tool Activity and retry.'
+                        : 'Taskforce reached the per-message tool limit. Review Tool Activity and retry.',
+                };
+                requestedToolCall = null;
             }
             if (workflowCompletionRequested && !mcpToolResults.some((toolResult) => (toolResult.name === 'complete_workflow_step' && toolResult.ok))) {
                 const incompletePrefix = 'WORKFLOW_STEP_INCOMPLETE:';

package/dist/server/routes/annotatedAttachments.js

@@ -11,7 +11,8 @@
  *   DELETE /api/taskforce/annotated-attachments/sessions/:id
  *   GET    /api/taskforce/annotated-attachments/sessions/:id/payload
  */
-import { ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY, resolveAppGateAccess, } from '../../runtime/appGates.js';
+import { ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY, } from '../../runtime/appGates.js';
+import { resolveNodeAppGateAccess } from '../../runtime/nodeAppGates.js';
 import { parseJsonBody } from './primitives.js';
 import { resolveErrorStatusCode } from './shared.js';
 import { getImageReferenceLabel, parseImageReference } from '../../utils/imageReferences.js';
@@ -37,7 +38,7 @@ export function registerAnnotatedAttachmentRoutes(deps) {
     const ensureAnnotatedAttachmentAccess = (req, res, workspaceId) => {
         if (!ensureAppAccess(req, res))
             return false;
-        const gate = resolveAppGateAccess(ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY);
+        const gate = resolveNodeAppGateAccess(ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY);
         if (gate.allowed)
             return true;
         writeJson(res, 403, {

package/dist/server/routes/auth.js

@@ -60,6 +60,7 @@ import { buildGithubAuthUrl, exchangeGithubCode } from '../auth/providers/github
 import { hasValidSession, createClearSessionCookie, createSessionTokenCookie, resolveRequestAccess, resolveSessionCookieAttributesForRequest, } from '../auth.js';
 import { sendEmail } from '../email.js';
 import { resolveDeploymentConfig } from '../../config/deployment.js';
+import { resolveNodeAppGateAccessMap } from '../../runtime/nodeAppGates.js';
 import { resolveTaskMetadataActivationCapability } from '../../sync/v3/taskMetadataActivation.js';
 import { resolveTaskCreateActivationCapability } from '../../sync/v3/taskCreateActivation.js';
 import { resolveTaskStatusActivationCapability } from '../../sync/v3/taskStatusActivation.js';
@@ -401,7 +402,7 @@ export function registerAuthRoutes(deps) {
             : 'Reset your Taskforce password';
         const text = kind === 'verify-email'
             ? `Welcome to Taskforce.\n\nYou're almost in. Enter this verification token on the verification screen to activate your account:\n\n${token}\n\nPrefer the faster route? Open the link below to verify your email automatically:\n${link}\n\nIf you didn't create a Taskforce account, you can safely ignore this email.`
-            : `Reset your Taskforce password using this link:\n${link}\n\nIf you did not request this reset, you can ignore this message.`;
+            : `Enter this password reset token on the reset screen:\n\n${token}\n\nOr reset your Taskforce password using this link:\n${link}\n\nIf you did not request this reset, you can ignore this message.`;
         const result = await sendEmail({
             to: email,
             subject,
@@ -470,6 +471,7 @@ export function registerAuthRoutes(deps) {
                 authSource: runtimeContract.authSource,
                 workspaceMode: runtimeContract.workspaceMode,
                 workspaceSwitchingEnabled: runtimeContract.workspaceSwitchingEnabled,
+                appGates: resolveNodeAppGateAccessMap(process.env),
                 syncV3
             }
         }));

package/dist/server/routes/documents.d.ts

@@ -8,6 +8,8 @@
  *   POST   /api/taskforce/context-upload/init
  *   POST   /api/taskforce/context-upload/finalize
  *   POST   /api/taskforce/context-upload
+ *   POST   /api/taskforce/context-upload/draft/promote
+ *   POST   /api/taskforce/context-upload/draft/discard
  *   GET    /api/taskforce/context/:filename
  *   GET    /api/taskforce/documents/:assetId/content
  *   GET    /api/taskforce/context-link
@@ -39,7 +41,7 @@ type AssetMetadata = DocumentRegistryEntry & {
     originalFilename?: string | null;
 };
 interface CanonicalReadResult {
-    statusCode: 200 | 302 | 404;
+    statusCode: 200 | 302 | 404 | 409;
     headers?: Record<string, string>;
     body?: Buffer;
 }
@@ -81,6 +83,7 @@ export interface DocumentRouteDependencies {
         workspaceId?: string;
         taskId?: string | null;
         originalName?: string | null;
+        actorRef?: string | null;
     }) => Promise<{
         scan?: {
             verdict?: string;
@@ -110,7 +113,7 @@ export interface DocumentRouteDependencies {
     sanitizeDownloadFilename: (nameRaw: string, fallback?: string) => string;
     contentTypeForExt: (ext: string) => string;
     inferInlineDocumentFromPath: (pathValue: string | null | undefined) => boolean;
-    resolveCanonicalDocumentRead: (params: {
+    resolveCanonicalContentRead: (params: {
         asset: WorkspaceAssetEntry;
         forceDownload: boolean;
         requestedFilename?: string | null;

package/dist/server/routes/documents.js

@@ -8,6 +8,8 @@
  *   POST   /api/taskforce/context-upload/init
  *   POST   /api/taskforce/context-upload/finalize
  *   POST   /api/taskforce/context-upload
+ *   POST   /api/taskforce/context-upload/draft/promote
+ *   POST   /api/taskforce/context-upload/draft/discard
  *   GET    /api/taskforce/context/:filename
  *   GET    /api/taskforce/documents/:assetId/content
  *   GET    /api/taskforce/context-link
@@ -33,7 +35,7 @@ import { parsePlan } from '../../utils/planParser.js';
 import { getCanonicalDocumentName, getReadableDocumentName, isGeneratedDocumentName } from '../../utils/documentNames.js';
 import { createWorkspaceAssetAccessGuard } from './assetAccess.js';
 import { parseJsonBody } from './primitives.js';
-import { requestHeader, requestRuntimeMode, resolveErrorStatusCode } from './shared.js';
+import { requestHeader, requestHumanActorRef, requestRuntimeMode, requestUserId, resolveErrorStatusCode, } from './shared.js';
 import { resolveDeploymentConfig } from '../../config/deployment.js';
 import { isAiProfileAvatarStorageKey } from '../../utils/aiProfileAvatarPaths.js';
 import { createTaskHttpDurableRouters } from './durableTaskHttpRouters.js';
@@ -110,7 +112,7 @@ async function proxyCloudUserProfileAvatar(req, res, relativePath, contentTypeFo
     }
 }
 export function registerDocumentRoutes(deps) {
-    const { addRoute, core, context, requestWorkspaceId, ensureAdminRole, resolveEffectiveObjectStorageConfig, getObjectStorageClient, resolveStorageWorkspaceId, ensureContextUploadAllowed, parseStorageFolderSegments, buildCanonicalWorkspaceAssetRelativePath, inferAssetKindFromPath, appendStorageTelemetry, scanAndRecordDocument, buildTaskAttachmentPayload, workspaceAssetStore, taskAssetStore, normalizeDocumentPathInput, getAssetMetadata, getCanonicalAssetMetadata, documentRetentionDays, appendDocumentPurgeHistory, markAssetDeleted, isAssetDeleted, clearAssetDeleted, ensureWithinDir, sanitizeDownloadFilename, contentTypeForExt, inferInlineDocumentFromPath, resolveCanonicalDocumentRead, inferWorkspaceIdFromStoragePath, inferTaskIdFromStoragePath, } = deps;
+    const { addRoute, core, context, requestWorkspaceId, ensureAdminRole, resolveEffectiveObjectStorageConfig, getObjectStorageClient, resolveStorageWorkspaceId, ensureContextUploadAllowed, parseStorageFolderSegments, buildCanonicalWorkspaceAssetRelativePath, inferAssetKindFromPath, appendStorageTelemetry, scanAndRecordDocument, buildTaskAttachmentPayload, workspaceAssetStore, taskAssetStore, normalizeDocumentPathInput, getAssetMetadata, getCanonicalAssetMetadata, documentRetentionDays, appendDocumentPurgeHistory, markAssetDeleted, isAssetDeleted, clearAssetDeleted, ensureWithinDir, sanitizeDownloadFilename, contentTypeForExt, inferInlineDocumentFromPath, resolveCanonicalContentRead, inferWorkspaceIdFromStoragePath, inferTaskIdFromStoragePath, } = deps;
     const isTaskAttachmentDurable = (req, workspaceId) => (createTaskHttpDurableRouters({ core, context, req, workspaceId }).attachmentLinks.enabled);
     const durableUploadIdentity = (req, workspaceId, taskId) => {
         const normalizedTaskId = String(taskId || '').trim();
@@ -172,6 +174,69 @@ export function registerDocumentRoutes(deps) {
         return String(url.searchParams.get('workspaceId') || '').trim() || requestWorkspaceId(req);
     };
     const { ensureWorkspaceAssetAccess, isCloudAssetRequest } = createWorkspaceAssetAccessGuard({ core, context });
+    const readTaskDescriptionDraftUpload = (body) => {
+        const draftId = String(body?.draftUploadId || '').trim();
+        const purpose = String(body?.uploadPurpose || '').trim();
+        if (!draftId && !purpose)
+            return null;
+        if (purpose !== 'task-description-draft' || !/^[a-zA-Z0-9-]{16,160}$/.test(draftId)) {
+            throw Object.assign(new Error('Invalid task Description draft upload identity.'), { statusCode: 400 });
+        }
+        return { draftId, purpose };
+    };
+    const recordTaskDescriptionDraftUpload = (input) => {
+        const draft = readTaskDescriptionDraftUpload(input.body);
+        if (!draft || !workspaceAssetStore)
+            return;
+        workspaceAssetStore.recordUploadDraft({
+            workspaceId: input.workspaceId,
+            draftId: draft.draftId,
+            assetId: input.assetId,
+            storageKey: input.storageKey,
+            purpose: draft.purpose,
+            createdByUserId: String(requestUserId(input.req) || '').trim() || 'anonymous',
+        });
+    };
+    const retireOrDeleteTaskDescriptionDraftUploads = async (input) => {
+        if (!workspaceAssetStore)
+            return { total: 0, promoted: 0, discarded: 0 };
+        const records = workspaceAssetStore.listUploadDrafts(input);
+        const now = new Date();
+        const deletedAt = now.toISOString();
+        const purgeAfter = new Date(now.getTime() + documentRetentionDays * 86_400_000).toISOString();
+        let promoted = 0;
+        let discarded = 0;
+        for (const record of records) {
+            const links = workspaceAssetStore.listLinksForAsset(record.assetId, record.workspaceId);
+            if (links.length > 0) {
+                workspaceAssetStore.retireUploadDraft({
+                    workspaceId: record.workspaceId,
+                    draftId: record.draftId,
+                    assetId: record.assetId,
+                    retiredAt: deletedAt,
+                });
+                promoted += 1;
+                continue;
+            }
+            const asset = workspaceAssetStore.get(record.assetId, record.workspaceId);
+            if (asset && !asset.deletedAt) {
+                workspaceAssetStore.assertAssetDeletionAllowed(record.assetId, record.workspaceId);
+                workspaceAssetStore.markDeleted(record.assetId, record.workspaceId, deletedAt, purgeAfter);
+                core.notifyDocumentMetadataMutation(record.workspaceId, [record.storageKey], 'delete');
+            }
+            else if (!asset) {
+                await getObjectStorageClient()?.deleteObject(record.storageKey);
+            }
+            workspaceAssetStore.retireUploadDraft({
+                workspaceId: record.workspaceId,
+                draftId: record.draftId,
+                assetId: record.assetId,
+                retiredAt: deletedAt,
+            });
+            discarded += 1;
+        }
+        return { total: records.length, promoted, discarded };
+    };
     const removeDocumentAttachmentFromTaskAttachments = (attachmentsRaw, asset) => {
         const canonicalDocumentPath = `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`;
         const legacyContextPath = `/api/taskforce/context/${encodeURIComponent(asset.storageKey)}`;
@@ -260,6 +325,13 @@ export function registerDocumentRoutes(deps) {
         const relativeToStorage = canonicalAsset.relativePath;
         const relativePath = path.relative(projectRoot, path.join(basePath, relativeToStorage));
         if (objectStorageClient && resolvedObjectStorage.provider === 'r2' && resolvedObjectStorage.r2) {
+            recordTaskDescriptionDraftUpload({
+                req,
+                body,
+                workspaceId,
+                assetId: canonicalAsset.assetId,
+                storageKey: relativeToStorage,
+            });
             const uploadUrl = objectStorageClient.createSignedPutUrl(relativeToStorage, resolvedObjectStorage.r2.signedUploadTtlSeconds, String(mimeType || 'application/octet-stream'));
             appendStorageTelemetry('upload.initiated', {
                 path: relativeToStorage,
@@ -345,8 +417,19 @@ export function registerDocumentRoutes(deps) {
                 provider: 'r2',
                 workspaceId: inferWorkspaceIdFromStoragePath(relativeToStorage),
                 taskId: durableTaskAttachment ? null : taskId,
-                originalName: typeof body?.originalName === 'string' ? body.originalName.trim() : null
+                originalName: typeof body?.originalName === 'string' ? body.originalName.trim() : null,
+                actorRef: requestHumanActorRef(req),
             });
+            const finalizedAsset = workspaceAssetStore?.getByStorageKey(relativeToStorage, workspaceId);
+            if (finalizedAsset) {
+                recordTaskDescriptionDraftUpload({
+                    req,
+                    body,
+                    workspaceId,
+                    assetId: finalizedAsset.assetId,
+                    storageKey: relativeToStorage,
+                });
+            }
             if (durableTaskAttachment && taskId) {
                 attachUploadedAssetThroughDurableBoundary({
                     req,
@@ -456,7 +539,8 @@ export function registerDocumentRoutes(deps) {
                 provider: 'r2',
                 workspaceId,
                 taskId: durableTaskAttachment ? null : normalizedTaskId,
-                originalName: safeOriginal || actualFilename
+                originalName: safeOriginal || actualFilename,
+                actorRef: requestHumanActorRef(req),
             });
             appendStorageTelemetry('upload.completed', {
                 path: relativeToStorage,
@@ -476,7 +560,8 @@ export function registerDocumentRoutes(deps) {
                 provider: 'local',
                 workspaceId,
                 taskId: durableTaskAttachment ? null : normalizedTaskId,
-                originalName: safeOriginal || actualFilename
+                originalName: safeOriginal || actualFilename,
+                actorRef: requestHumanActorRef(req),
             });
             appendStorageTelemetry('upload.completed', {
                 path: relativeToStorage,
@@ -494,6 +579,16 @@ export function registerDocumentRoutes(deps) {
                 caption: safeOriginal || actualFilename,
             });
         }
+        const uploadedAsset = workspaceAssetStore?.getByStorageKey(relativeToStorage, workspaceId);
+        if (uploadedAsset) {
+            recordTaskDescriptionDraftUpload({
+                req,
+                body,
+                workspaceId,
+                assetId: uploadedAsset.assetId,
+                storageKey: relativeToStorage,
+            });
+        }
         res.writeHead(200, { 'Content-Type': 'application/json' });
         const attachment = buildTaskAttachmentPayload(relativeToStorage, {
             caption: safeOriginal || actualFilename,
@@ -508,6 +603,40 @@ export function registerDocumentRoutes(deps) {
             })
         }));
     });
+    addRoute('POST', '/api/taskforce/context-upload/draft/promote', async (req, res) => {
+        const body = await parseJsonBody(req);
+        const workspaceId = resolveStorageWorkspaceId(req, body);
+        const draft = readTaskDescriptionDraftUpload(body);
+        if (!workspaceId || !draft) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'workspaceId and draft upload identity are required.' }));
+            return;
+        }
+        const summary = await retireOrDeleteTaskDescriptionDraftUploads({
+            workspaceId,
+            draftId: draft.draftId,
+            createdByUserId: String(requestUserId(req) || '').trim() || 'anonymous',
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, ...summary }));
+    });
+    addRoute('POST', '/api/taskforce/context-upload/draft/discard', async (req, res) => {
+        const body = await parseJsonBody(req);
+        const workspaceId = resolveStorageWorkspaceId(req, body);
+        const draft = readTaskDescriptionDraftUpload(body);
+        if (!workspaceId || !draft) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'workspaceId and draft upload identity are required.' }));
+            return;
+        }
+        const summary = await retireOrDeleteTaskDescriptionDraftUploads({
+            workspaceId,
+            draftId: draft.draftId,
+            createdByUserId: String(requestUserId(req) || '').trim() || 'anonymous',
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, ...summary }));
+    });
     addRoute('GET', '/api/taskforce/context/:filename', async (req, res, params) => {
         const resolvedObjectStorage = resolveEffectiveObjectStorageConfig();
         const objectStorageClient = getObjectStorageClient();
@@ -556,8 +685,8 @@ export function registerDocumentRoutes(deps) {
             ? `attachment; filename="${resolvedDownloadName.replace(/"/g, '')}"`
             : 'inline';
         const shouldProxyInlineDocument = !forceDownload && (canonicalAsset?.kind === 'document' || inferInlineDocumentFromPath(normalizedRelative));
-        if (canonicalAsset?.kind === 'document' && !canonicalAsset.deletedAt) {
-            const response = await resolveCanonicalDocumentRead({
+        if (canonicalAsset && !canonicalAsset.deletedAt && (canonicalAsset.kind === 'document' || !filePath)) {
+            const response = await resolveCanonicalContentRead({
                 asset: canonicalAsset,
                 forceDownload,
                 requestedFilename
@@ -567,6 +696,11 @@ export function registerDocumentRoutes(deps) {
                 res.end('Context file not found');
                 return;
             }
+            if (response.statusCode === 409) {
+                res.writeHead(409, response.headers || { 'Content-Type': 'application/json' });
+                res.end(response.body);
+                return;
+            }
             if (forceDownload && response.statusCode === 302 && response.headers?.Location) {
                 res.writeHead(302, { Location: response.headers.Location });
                 res.end();
@@ -659,7 +793,7 @@ export function registerDocumentRoutes(deps) {
             res.end('Document scan pending');
             return;
         }
-        const response = await resolveCanonicalDocumentRead({
+        const response = await resolveCanonicalContentRead({
             asset,
             forceDownload,
             requestedFilename
@@ -669,6 +803,11 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'Document content not found' }));
             return;
         }
+        if (response.statusCode === 409) {
+            res.writeHead(409, response.headers || { 'Content-Type': 'application/json' });
+            res.end(response.body);
+            return;
+        }
         if (forceDownload && response.statusCode === 302 && response.headers?.Location) {
             res.writeHead(302, { Location: response.headers.Location });
             res.end();
@@ -791,6 +930,12 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
             return;
         }
+        const workspaceId = requestWorkspaceId(req);
+        const draftExpiry = new Date(Date.now() - 30 * 86_400_000).toISOString();
+        const draftSummary = await retireOrDeleteTaskDescriptionDraftUploads({
+            workspaceId,
+            createdBefore: draftExpiry,
+        });
         const { basePath } = core.getPaths();
         const summary = await purgeExpiredDocuments({
             basePath,
@@ -804,7 +949,7 @@ export function registerDocumentRoutes(deps) {
             provider: resolveEffectiveObjectStorageConfig().provider
         });
         res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ success: true, ...summary }));
+        res.end(JSON.stringify({ success: true, ...summary, draftUploads: draftSummary }));
     });
     addRoute('GET', '/api/taskforce/documents', async (req, res) => {
         const workspaceId = requestWorkspaceIdWithQuery(req);
@@ -1059,7 +1204,7 @@ export function registerDocumentRoutes(deps) {
             core.updateTask(targetId, {
                 attachments: [...(Array.isArray(task.attachments) ? task.attachments : []), payload],
             }, workspaceId, {
-                actorRef: 'user',
+                actorRef: requestHumanActorRef(req),
                 saveSource: 'manual',
             });
         }
@@ -1124,7 +1269,7 @@ export function registerDocumentRoutes(deps) {
                 else {
                     const updatedAttachments = removeDocumentAttachmentFromTaskAttachments(task.attachments, asset);
                     core.updateTask(taskId, { attachments: updatedAttachments }, workspaceId, {
-                        actorRef: 'user',
+                        actorRef: requestHumanActorRef(req),
                         saveSource: 'manual'
                     });
                 }
@@ -1280,7 +1425,8 @@ export function registerDocumentRoutes(deps) {
                         contentType: 'text/markdown; charset=utf-8',
                         provider: 'r2',
                         workspaceId: assetWorkspaceId,
-                        originalName: metadata.logicalName || metadata.originalFilename || path.basename(normalizedStoragePath)
+                        originalName: metadata.logicalName || metadata.originalFilename || path.basename(normalizedStoragePath),
+                        actorRef: requestHumanActorRef(req),
                     });
                     clearAssetDeleted(normalizedStoragePath);
                     const version = workspaceAssetStore
@@ -1336,7 +1482,8 @@ export function registerDocumentRoutes(deps) {
                     contentType: 'text/markdown; charset=utf-8',
                     provider: 'local',
                     workspaceId: assetWorkspaceId,
-                    originalName: path.basename(normalizedStoragePath)
+                    originalName: path.basename(normalizedStoragePath),
+                    actorRef: requestHumanActorRef(req),
                 });
                 clearAssetDeleted(normalizedStoragePath);
                 version = workspaceAssetStore