@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/server/routes/documents.js

@@ -24,20 +24,28 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { createHash } from 'crypto';
 import { normalizeTaskDataRelativePath } from '../../storage/objectStorageClient.js';
 import { resolveExistingStorageKeyFilePathInsideRoot } from '../../utils/pathSafety.js';
 import { shouldUseProvisionalTaskReferences } from '../../utils/taskReferences.js';
 import { purgeExpiredDocuments } from '../../storage/documentPurge.js';
 import { parsePlan } from '../../utils/planParser.js';
 import { getCanonicalDocumentName, getReadableDocumentName, isGeneratedDocumentName } from '../../utils/documentNames.js';
-import { requestRuntimeMode } from './shared.js';
+import { createWorkspaceAssetAccessGuard } from './assetAccess.js';
 import { parseJsonBody } from './primitives.js';
+import { requestHeader, requestRuntimeMode, resolveErrorStatusCode } from './shared.js';
 import { resolveDeploymentConfig } from '../../config/deployment.js';
+import { isAiProfileAvatarStorageKey } from '../../utils/aiProfileAvatarPaths.js';
+import { createTaskHttpDurableRouters } from './durableTaskHttpRouters.js';
+import { getDocumentReferenceLabel } from '../../utils/documentReferences.js';
+import { getImageReferenceLabel } from '../../utils/imageReferences.js';
 function isUserProfileAvatarPath(relativePath) {
     return /^users\/[^/]+\/profile\/avatar\/[^/]+$/i.test(String(relativePath || '').replace(/\\/g, '/'));
 }
 function isAiProfileAvatarPath(relativePath) {
-    return /^workspaces\/[^/]+\/assets\/images\/ai-profiles\/[^/]+\/avatar\/[^/]+$/i.test(String(relativePath || '').replace(/\\/g, '/'));
+    const normalized = String(relativePath || '').replace(/\\/g, '/');
+    const workspaceId = normalized.match(/^workspaces\/([^/]+)\//)?.[1] || '';
+    return isAiProfileAvatarStorageKey(normalized, workspaceId);
 }
 function resolveRequestOrigin(req) {
     const host = String(req.headers.host || '').trim();
@@ -103,6 +111,67 @@ 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 isTaskAttachmentDurable = (req, workspaceId) => (createTaskHttpDurableRouters({ core, context, req, workspaceId }).attachmentLinks.enabled);
+    const durableUploadIdentity = (req, workspaceId, taskId) => {
+        const normalizedTaskId = String(taskId || '').trim();
+        if (!normalizedTaskId || !isTaskAttachmentDurable(req, workspaceId))
+            return null;
+        const operationId = requestHeader(req, 'x-taskforce-operation-id', '').trim();
+        if (!operationId)
+            return null;
+        const digest = createHash('sha256').update(JSON.stringify({ workspaceId, taskId: normalizedTaskId, operationId }))
+            .digest('hex');
+        return { operationId, assetId: `asset-${digest.slice(0, 32)}`, suffix: digest.slice(0, 24) };
+    };
+    const requireDurableUploadIdentity = (req, res, workspaceId, taskId) => {
+        const identity = durableUploadIdentity(req, workspaceId, taskId);
+        if (identity || !String(taskId || '').trim() || !isTaskAttachmentDurable(req, workspaceId))
+            return identity;
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            error: 'x-taskforce-operation-id is required for durable task attachment uploads.',
+            code: 'WORKSPACE_SYNC_OPERATION_ID_REQUIRED',
+        }));
+        return undefined;
+    };
+    const attachUploadedAssetThroughDurableBoundary = (input) => {
+        if (!workspaceAssetStore)
+            return false;
+        const durableRouters = createTaskHttpDurableRouters({
+            core,
+            context,
+            req: input.req,
+            workspaceId: input.workspaceId,
+        });
+        if (!durableRouters.attachmentLinks.enabled)
+            return false;
+        const asset = workspaceAssetStore.getByStorageKey(input.storageKey, input.workspaceId);
+        if (!asset || asset.deletedAt)
+            throw new Error('Uploaded attachment asset was not persisted.');
+        const existing = core.listTaskAttachmentLinksForDurableSync(input.taskId, input.workspaceId);
+        if (existing.some((entry) => entry.assetId === asset.assetId))
+            return true;
+        durableRouters.attachmentLinks.replace({
+            taskId: input.taskId,
+            links: [...existing, {
+                    assetId: asset.assetId,
+                    role: asset.kind === 'image' ? 'image' : 'attachment',
+                    order: existing.length,
+                    ...(input.caption ? { caption: input.caption } : {}),
+                    originalFilename: asset.originalFilename,
+                    referenceNumber: asset.referenceNumber || null,
+                    referenceLabel: asset.kind === 'document'
+                        ? getDocumentReferenceLabel(asset) || null
+                        : asset.kind === 'image' ? getImageReferenceLabel(asset) || null : null,
+                }],
+        });
+        return true;
+    };
+    const requestWorkspaceIdWithQuery = (req) => {
+        const url = new URL(req.url || '', 'http://localhost');
+        return String(url.searchParams.get('workspaceId') || '').trim() || requestWorkspaceId(req);
+    };
+    const { ensureWorkspaceAssetAccess, isCloudAssetRequest } = createWorkspaceAssetAccessGuard({ core, context });
     const removeDocumentAttachmentFromTaskAttachments = (attachmentsRaw, asset) => {
         const canonicalDocumentPath = `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`;
         const legacyContextPath = `/api/taskforce/context/${encodeURIComponent(asset.storageKey)}`;
@@ -148,6 +217,9 @@ export function registerDocumentRoutes(deps) {
             requestedBytes: Number.isFinite(requestedBytes) ? requestedBytes : null
         }))
             return;
+        const durableIdentity = requireDurableUploadIdentity(req, res, workspaceId, taskId);
+        if (String(taskId || '').trim() && isTaskAttachmentDurable(req, workspaceId) && !durableIdentity)
+            return;
         const folderSegments = parseStorageFolderSegments(folderPath);
         if (folderSegments === null) {
             res.writeHead(400, { 'Content-Type': 'application/json' });
@@ -173,7 +245,7 @@ export function registerDocumentRoutes(deps) {
         const safeBase = (safeOriginal ? path.basename(safeOriginal, originalExt) : 'context-file')
             .replace(/[^a-zA-Z0-9._-]/g, '-')
             .slice(0, 64) || 'context-file';
-        const actualFilename = `${safeBase}-${Date.now()}${extension}`;
+        const actualFilename = `${safeBase}-${durableIdentity?.suffix || Date.now()}${extension}`;
         const { basePath, projectRoot } = core.getPaths();
         const kind = String(mimeType || '').startsWith('image/')
             ? 'image'
@@ -182,7 +254,8 @@ export function registerDocumentRoutes(deps) {
             workspaceIdRaw: workspaceId,
             kind,
             filename: actualFilename,
-            folderSegments
+            folderSegments,
+            ...(durableIdentity ? { assetId: durableIdentity.assetId } : {}),
         });
         const relativeToStorage = canonicalAsset.relativePath;
         const relativePath = path.relative(projectRoot, path.join(basePath, relativeToStorage));
@@ -234,6 +307,17 @@ export function registerDocumentRoutes(deps) {
             return;
         }
         const workspaceId = inferWorkspaceIdFromStoragePath(relativeToStorage) || requestWorkspaceId(req);
+        const finalizeTaskId = typeof body?.taskId === 'string' && body.taskId.trim().length > 0
+            ? body.taskId.trim()
+            : inferTaskIdFromStoragePath(relativeToStorage);
+        const durableIdentity = requireDurableUploadIdentity(req, res, workspaceId, finalizeTaskId);
+        if (finalizeTaskId && isTaskAttachmentDurable(req, workspaceId) && !durableIdentity)
+            return;
+        if (!ensureWorkspaceAssetAccess(req, res, {
+            operation: 'upload-finalize',
+            storageKey: relativeToStorage
+        }).allowed)
+            return;
         if (!ensureContextUploadAllowed(req, res, workspaceId))
             return;
         if (!objectStorageClient) {
@@ -252,18 +336,26 @@ export function registerDocumentRoutes(deps) {
         }))
             return;
         try {
-            const taskId = typeof body?.taskId === 'string' && body.taskId.trim().length > 0
-                ? body.taskId.trim()
-                : inferTaskIdFromStoragePath(relativeToStorage);
+            const taskId = finalizeTaskId;
+            const durableTaskAttachment = !!taskId && isTaskAttachmentDurable(req, workspaceId);
             const metadata = await scanAndRecordDocument({
                 relativeToStorage,
                 buffer: object.body,
                 contentType: String(body?.mimeType || object.contentType || 'application/octet-stream'),
                 provider: 'r2',
                 workspaceId: inferWorkspaceIdFromStoragePath(relativeToStorage),
-                taskId,
+                taskId: durableTaskAttachment ? null : taskId,
                 originalName: typeof body?.originalName === 'string' ? body.originalName.trim() : null
             });
+            if (durableTaskAttachment && taskId) {
+                attachUploadedAssetThroughDurableBoundary({
+                    req,
+                    workspaceId,
+                    taskId,
+                    storageKey: relativeToStorage,
+                    caption: typeof body?.originalName === 'string' ? body.originalName.trim() : null,
+                });
+            }
             appendStorageTelemetry('upload.finalized', {
                 path: relativeToStorage,
                 status: metadata.scan?.verdict || 'unknown',
@@ -304,6 +396,9 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'folderPath cannot contain . or .. segments.' }));
             return;
         }
+        const durableIdentity = requireDurableUploadIdentity(req, res, workspaceId, taskId);
+        if (String(taskId || '').trim() && isTaskAttachmentDurable(req, workspaceId) && !durableIdentity)
+            return;
         if (!file || typeof file !== 'string') {
             res.writeHead(400, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'No file data' }));
@@ -335,7 +430,7 @@ export function registerDocumentRoutes(deps) {
         const safeBase = (safeOriginal ? path.basename(safeOriginal, originalExt) : 'context-file')
             .replace(/[^a-zA-Z0-9._-]/g, '-')
             .slice(0, 64) || 'context-file';
-        const actualFilename = `${safeBase}-${Date.now()}${extension}`;
+        const actualFilename = `${safeBase}-${durableIdentity?.suffix || Date.now()}${extension}`;
         const { basePath, projectRoot } = core.getPaths();
         const buffer = Buffer.from(base64Data, 'base64');
         if (!ensureContextUploadAllowed(req, res, workspaceId, {
@@ -346,8 +441,11 @@ export function registerDocumentRoutes(deps) {
             workspaceIdRaw: workspaceId,
             kind: mimeType.startsWith('image/') ? 'image' : inferAssetKindFromPath(actualFilename),
             filename: actualFilename,
-            folderSegments
+            folderSegments,
+            ...(durableIdentity ? { assetId: durableIdentity.assetId } : {}),
         }).relativePath;
+        const normalizedTaskId = typeof taskId === 'string' && taskId.trim().length > 0 ? taskId.trim() : null;
+        const durableTaskAttachment = !!normalizedTaskId && isTaskAttachmentDurable(req, workspaceId);
         let relativePath;
         if (objectStorageClient) {
             await objectStorageClient.putObject(relativeToStorage, buffer, mimeType || 'application/octet-stream');
@@ -357,7 +455,7 @@ export function registerDocumentRoutes(deps) {
                 contentType: mimeType || 'application/octet-stream',
                 provider: 'r2',
                 workspaceId,
-                taskId,
+                taskId: durableTaskAttachment ? null : normalizedTaskId,
                 originalName: safeOriginal || actualFilename
             });
             appendStorageTelemetry('upload.completed', {
@@ -377,7 +475,7 @@ export function registerDocumentRoutes(deps) {
                 contentType: mimeType || 'application/octet-stream',
                 provider: 'local',
                 workspaceId,
-                taskId,
+                taskId: durableTaskAttachment ? null : normalizedTaskId,
                 originalName: safeOriginal || actualFilename
             });
             appendStorageTelemetry('upload.completed', {
@@ -387,10 +485,19 @@ export function registerDocumentRoutes(deps) {
             });
             relativePath = path.relative(projectRoot, filePath);
         }
+        if (durableTaskAttachment && normalizedTaskId) {
+            attachUploadedAssetThroughDurableBoundary({
+                req,
+                workspaceId,
+                taskId: normalizedTaskId,
+                storageKey: relativeToStorage,
+                caption: safeOriginal || actualFilename,
+            });
+        }
         res.writeHead(200, { 'Content-Type': 'application/json' });
         const attachment = buildTaskAttachmentPayload(relativeToStorage, {
             caption: safeOriginal || actualFilename,
-            taskId: typeof taskId === 'string' && taskId.trim().length > 0 ? taskId.trim() : null
+            taskId: normalizedTaskId
         });
         res.end(JSON.stringify({
             success: true,
@@ -412,6 +519,12 @@ export function registerDocumentRoutes(deps) {
         const normalizedRelative = normalizeTaskDataRelativePath(decoded);
         const contextAsset = normalizedRelative ? getAssetMetadata(normalizedRelative) : null;
         const canonicalAsset = normalizedRelative ? getCanonicalAssetMetadata(normalizedRelative) : null;
+        if (normalizedRelative && !ensureWorkspaceAssetAccess(req, res, {
+            operation: 'read',
+            asset: canonicalAsset,
+            storageKey: normalizedRelative
+        }).allowed)
+            return;
         if (normalizedRelative && contextAsset?.quarantineStatus === 'quarantined') {
             res.writeHead(423, { 'Content-Type': 'text/plain' });
             res.end('Context file is quarantined');
@@ -514,7 +627,7 @@ export function registerDocumentRoutes(deps) {
         res.end('Context file not found');
     });
     addRoute('GET', '/api/taskforce/documents/:assetId/content', async (req, res, params) => {
-        const workspaceId = requestWorkspaceId(req);
+        const workspaceId = requestWorkspaceIdWithQuery(req);
         const assetId = String(params.assetId || '').trim();
         const url = new URL(req.url || '', 'http://localhost');
         const forceDownload = url.searchParams.get('download') === '1';
@@ -530,6 +643,12 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'Document not found' }));
             return;
         }
+        if (!ensureWorkspaceAssetAccess(req, res, {
+            operation: 'read',
+            asset,
+            fallbackWorkspaceId: workspaceId
+        }).allowed)
+            return;
         if (asset.scanStatus === 'infected') {
             res.writeHead(423, { 'Content-Type': 'text/plain' });
             res.end('Document is quarantined');
@@ -572,6 +691,11 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'path query parameter is required' }));
             return;
         }
+        if (isCloudAssetRequest(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Context links are only available in local runtime.' }));
+            return;
+        }
         const resolvedPath = path.isAbsolute(linkedPath)
             ? path.resolve(linkedPath)
             : path.resolve(projectRoot, linkedPath);
@@ -605,6 +729,13 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'File not found' }));
             return;
         }
+        const canonicalAsset = getCanonicalAssetMetadata(normalizedRelative);
+        if (!ensureWorkspaceAssetAccess(req, res, {
+            operation: 'delete',
+            asset: canonicalAsset,
+            storageKey: normalizedRelative
+        }).allowed)
+            return;
         const filePath = ensureWithinDir(path.join(basePath, normalizedRelative), basePath);
         if (!objectStorageClient && (!filePath || !fs.existsSync(filePath)) && !getAssetMetadata(normalizedRelative)) {
             res.writeHead(404, { 'Content-Type': 'application/json' });
@@ -676,7 +807,7 @@ export function registerDocumentRoutes(deps) {
         res.end(JSON.stringify({ success: true, ...summary }));
     });
     addRoute('GET', '/api/taskforce/documents', async (req, res) => {
-        const workspaceId = requestWorkspaceId(req);
+        const workspaceId = requestWorkspaceIdWithQuery(req);
         function inferDocType(filename) {
             const base = path.basename(filename, path.extname(filename)).toLowerCase();
             if (base.includes('implementation-plan') || base.includes('implementation_plan'))
@@ -698,43 +829,41 @@ export function registerDocumentRoutes(deps) {
             const fallbackFilename = path.basename(normalizedPath);
             const inferredTitle = inferTitle(fallbackFilename, input.assetId || null) || fallbackFilename || 'Untitled document';
             const originalFilename = String(input.originalFilename || '').trim() || fallbackFilename || null;
-            const displayName = getCanonicalDocumentName({
-                logicalName: String(input.displayName || '').trim() || null,
+            const title = getCanonicalDocumentName({
                 title: String(input.title || '').trim() || null,
                 originalFilename,
                 fsPath: normalizedPath,
-                assetId: input.assetId || null,
+                assetId: input.assetId,
             }) || inferredTitle;
-            const title = String(input.title || '').trim()
-                || displayName
-                || inferredTitle;
             const taskId = String(input.taskId || '').trim() || null;
-            const attachmentCount = typeof input.attachmentCount === 'number' && Number.isFinite(input.attachmentCount)
-                ? Math.max(0, Math.floor(input.attachmentCount))
-                : (taskId ? 1 : 0);
+            const targets = Array.isArray(input.targets) ? input.targets : [];
+            const attachmentCount = targets.length;
             const attachmentState = input.attachmentState === 'attached'
                 || input.attachmentState === 'unattached'
-                ? (attachmentCount > 0 || taskId
+                ? (attachmentCount > 0
                     ? 'attached'
                     : 'unattached')
-                : (attachmentCount > 0 || taskId ? 'attached' : 'unattached');
+                : (attachmentCount > 0 ? 'attached' : 'unattached');
             return {
-                id: input.id,
-                assetId: input.assetId || null,
+                assetId: input.assetId,
                 referenceNumber: typeof input.referenceNumber === 'number' && Number.isFinite(input.referenceNumber)
                     ? Math.max(1, Math.floor(input.referenceNumber))
                     : null,
                 referenceLabel: String(input.referenceLabel || '').trim() || null,
+                version: typeof input.version === 'number' && Number.isFinite(input.version)
+                    ? Math.max(1, Math.floor(input.version))
+                    : null,
                 fsPath: normalizedPath,
                 apiUrl: input.apiUrl,
                 taskId,
-                displayName,
                 originalFilename,
                 title,
                 docType: input.docType,
                 sizeBytes: typeof input.sizeBytes === 'number' && Number.isFinite(input.sizeBytes) ? Math.max(0, input.sizeBytes) : 0,
                 updatedAt: input.updatedAt || null,
+                createdAt: input.createdAt || null,
                 editable: input.editable !== false,
+                targets,
                 attachmentCount,
                 attachmentState
             };
@@ -752,75 +881,80 @@ export function registerDocumentRoutes(deps) {
         // Shared document listing is canonical-document-only. Raw files under
         // .taskforce/docs are intentionally excluded because they are not
         // workspace-scoped managed documents.
-        const canonicalDocuments = workspaceAssetStore?.listAllByWorkspace(workspaceId, {
+        const canonicalDocuments = workspaceAssetStore?.listDocumentsByWorkspace(workspaceId, {
             includeDeleted: false,
-            kind: 'document'
         }) || [];
         for (const asset of canonicalDocuments) {
             const filename = asset.originalFilename || path.basename(asset.storageKey);
-            const repairedReadableName = getCanonicalDocumentName({
-                logicalName: asset.logicalName || null,
+            const repairedReadableTitle = getCanonicalDocumentName({
                 displayName: null,
+                title: asset.title,
                 originalFilename: asset.originalFilename || filename,
                 fsPath: asset.storageKey,
                 assetId: asset.assetId || null,
             });
             const activeLinks = (workspaceAssetStore?.listLinksForAsset(asset.assetId, workspaceId) || [])
-                .filter((link) => !link.deletedAt)
-                .filter((link) => link.targetType !== 'task' || (!!link.taskId && !!core.getTask(link.taskId, workspaceId)));
+                .filter((link) => !link.deletedAt);
+            const targets = activeLinks.flatMap((link) => {
+                const entity = link.targetType === 'task'
+                    ? core.getTask(link.targetId, workspaceId)
+                    : link.targetType === 'initiative'
+                        ? core.getInitiative(link.targetId, workspaceId)
+                        : core.getWorkstream(link.targetId, workspaceId);
+                // Preserve active planning links even when their projection has not
+                // hydrated yet. Task links retain the existing deleted-task guard.
+                if (link.targetType === 'task' && !entity)
+                    return [];
+                const fallbackTitle = link.targetType === 'initiative'
+                    ? 'Linked initiative'
+                    : link.targetType === 'workstream'
+                        ? 'Linked workstream'
+                        : 'Linked task';
+                return [{
+                        targetType: link.targetType,
+                        targetId: link.targetId,
+                        referenceLabel: String(entity?.referenceLabel || '').trim() || null,
+                        title: String(entity?.title || link.displayName || fallbackTitle).trim(),
+                        role: link.role,
+                    }];
+            });
             const activeTaskLinks = activeLinks
-                .filter((link) => link.targetType === 'task' && !!link.taskId)
-                .filter((link) => !!core.getTask(link.taskId, workspaceId));
+                .filter((link) => link.targetType === 'task')
+                .filter((link) => targets.some((target) => (target.targetType === 'task' && target.targetId === link.targetId)));
             const firstLink = activeTaskLinks[0] || null;
-            const repairedLogicalName = isGeneratedDocumentName(asset.logicalName || null, asset.assetId || null)
+            const repairedTitle = isGeneratedDocumentName(asset.title, asset.assetId || null)
                 ? (String(firstLink?.displayName || '').trim()
-                    || repairedReadableName)
+                    || repairedReadableTitle)
                 : null;
-            if (repairedLogicalName && repairedLogicalName !== asset.logicalName) {
-                workspaceAssetStore?.upsertAsset({
+            if (repairedTitle && repairedTitle !== asset.title) {
+                workspaceAssetStore?.renameDocumentTitle({
                     assetId: asset.assetId,
                     workspaceId: asset.workspaceId,
-                    kind: asset.kind,
-                    logicalName: repairedLogicalName,
-                    originalFilename: asset.originalFilename,
-                    mimeType: asset.mimeType,
-                    storageProvider: asset.storageProvider,
-                    storageKey: asset.storageKey,
-                    contentSha256: asset.contentSha256,
-                    sizeBytes: asset.sizeBytes,
-                    documentId: asset.documentId,
-                    version: asset.version,
-                    isLatest: asset.isLatest,
-                    scanStatus: asset.scanStatus,
-                    scanEngine: asset.scanEngine,
-                    scanDetails: asset.scanDetails,
-                    createdByUserId: asset.createdByUserId,
-                    createdAt: asset.createdAt,
+                    title: repairedTitle,
                     updatedAt: asset.updatedAt || new Date().toISOString(),
-                    deletedAt: asset.deletedAt,
-                    purgeAfter: asset.purgeAfter
                 });
             }
-            const readableName = repairedLogicalName || repairedReadableName;
+            const title = repairedTitle || repairedReadableTitle;
             pushDocument({
-                id: asset.assetId || asset.storageKey,
-                assetId: asset.assetId || null,
+                assetId: asset.assetId,
                 referenceNumber: asset.referenceNumber,
                 referenceLabel: asset.referenceNumber ? `D-${asset.referenceNumber}` : null,
+                version: asset.version,
                 fsPath: asset.storageKey,
                 apiUrl: asset.assetId
                     ? `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`
                     : `/api/taskforce/context/${encodeURIComponent(asset.storageKey)}`,
                 taskId: firstLink?.taskId || inferTaskIdFromStoragePath(asset.storageKey),
-                displayName: readableName,
                 originalFilename: asset.originalFilename || null,
-                title: readableName,
+                title,
                 docType: inferDocType(filename),
                 sizeBytes: asset.sizeBytes ?? 0,
                 updatedAt: asset.updatedAt || null,
+                createdAt: asset.createdAt || null,
                 editable: true,
-                attachmentCount: activeLinks.length,
-                attachmentState: activeLinks.length > 0 ? 'attached' : 'unattached',
+                targets,
+                attachmentCount: targets.length,
+                attachmentState: targets.length > 0 ? 'attached' : 'unattached',
             });
         }
         documents.sort((a, b) => {
@@ -836,7 +970,7 @@ export function registerDocumentRoutes(deps) {
         res.end(JSON.stringify({ documents }));
     });
     addRoute('POST', '/api/taskforce/documents/:assetId/attach', async (req, res, params) => {
-        const workspaceId = requestWorkspaceId(req);
+        const workspaceId = requestWorkspaceIdWithQuery(req);
         const assetId = String(params.assetId || '').trim();
         const body = await parseJsonBody(req);
         const targetType = String(body?.targetType || 'task').trim();
@@ -856,12 +990,18 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'Only task attachments are supported from the document manager right now.' }));
             return;
         }
-        const asset = workspaceAssetStore.get(assetId, workspaceId);
-        if (!asset || asset.kind !== 'document' || asset.deletedAt) {
+        const asset = workspaceAssetStore.getDocument(assetId, workspaceId);
+        if (!asset || asset.deletedAt) {
             res.writeHead(404, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Document not found.' }));
             return;
         }
+        if (!ensureWorkspaceAssetAccess(req, res, {
+            operation: 'write',
+            asset,
+            fallbackWorkspaceId: workspaceId
+        }).allowed)
+            return;
         const task = core.getTask(targetId, workspaceId);
         if (!task) {
             res.writeHead(404, { 'Content-Type': 'application/json' });
@@ -887,8 +1027,7 @@ export function registerDocumentRoutes(deps) {
             caption: getCanonicalDocumentName({
                 assetId: asset.assetId,
                 fsPath: asset.storageKey,
-                logicalName: asset.logicalName || null,
-                title: asset.logicalName || asset.originalFilename,
+                title: asset.title,
                 originalFilename: asset.originalFilename,
             }),
             assetId: asset.assetId,
@@ -900,12 +1039,30 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'Failed to build attachment payload for this document.' }));
             return;
         }
-        core.updateTask(targetId, {
-            attachments: [...(Array.isArray(task.attachments) ? task.attachments : []), payload],
-        }, workspaceId, {
-            actorRef: 'user',
-            saveSource: 'manual',
-        });
+        const durableRouters = createTaskHttpDurableRouters({ core, context, req, workspaceId });
+        if (durableRouters.attachmentLinks.enabled) {
+            const links = core.listTaskAttachmentLinksForDurableSync(targetId, workspaceId);
+            durableRouters.attachmentLinks.replace({
+                taskId: targetId,
+                links: [...links, {
+                        assetId: asset.assetId,
+                        role: 'attachment',
+                        order: links.length,
+                        caption: String(payload.caption || asset.title || asset.originalFilename),
+                        originalFilename: asset.originalFilename,
+                        referenceNumber: asset.referenceNumber || null,
+                        referenceLabel: getDocumentReferenceLabel(asset) || null,
+                    }],
+            });
+        }
+        else {
+            core.updateTask(targetId, {
+                attachments: [...(Array.isArray(task.attachments) ? task.attachments : []), payload],
+            }, workspaceId, {
+                actorRef: 'user',
+                saveSource: 'manual',
+            });
+        }
         core.notifyDocumentMetadataMutation(workspaceId, [asset.storageKey], 'upsert');
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({
@@ -917,7 +1074,7 @@ export function registerDocumentRoutes(deps) {
         }));
     });
     addRoute('DELETE', '/api/taskforce/documents/:assetId', async (req, res, params) => {
-        const workspaceId = requestWorkspaceId(req);
+        const workspaceId = requestWorkspaceIdWithQuery(req);
         const assetId = String(params.assetId || '').trim();
         const body = await parseJsonBody(req);
         const forceDetach = body?.forceDetach === true;
@@ -932,6 +1089,12 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'Document not found' }));
             return;
         }
+        if (!ensureWorkspaceAssetAccess(req, res, {
+            operation: 'delete',
+            asset,
+            fallbackWorkspaceId: workspaceId
+        }).allowed)
+            return;
         const activeLinks = workspaceAssetStore.listLinksForAsset(asset.assetId, workspaceId)
             .filter((link) => !link.deletedAt)
             .filter((link) => link.targetType === 'task' && !!link.taskId)
@@ -951,13 +1114,23 @@ export function registerDocumentRoutes(deps) {
                 const task = core.getTask(taskId, workspaceId);
                 if (!task)
                     continue;
-                const updatedAttachments = removeDocumentAttachmentFromTaskAttachments(task.attachments, asset);
-                core.updateTask(taskId, { attachments: updatedAttachments }, workspaceId, {
-                    actorRef: 'user',
-                    saveSource: 'manual'
-                });
+                const durableRouters = createTaskHttpDurableRouters({ core, context, req, workspaceId });
+                if (durableRouters.attachmentLinks.enabled) {
+                    const links = core.listTaskAttachmentLinksForDurableSync(taskId, workspaceId)
+                        .filter((entry) => entry.assetId !== asset.assetId)
+                        .map((entry, order) => ({ ...entry, order }));
+                    durableRouters.createAttachmentLinksRouter(durableRouters.deriveChildOperationId('document-force-detach', 0, taskId)).replace({ taskId, links });
+                }
+                else {
+                    const updatedAttachments = removeDocumentAttachmentFromTaskAttachments(task.attachments, asset);
+                    core.updateTask(taskId, { attachments: updatedAttachments }, workspaceId, {
+                        actorRef: 'user',
+                        saveSource: 'manual'
+                    });
+                }
             }
         }
+        workspaceAssetStore.assertAssetDeletionAllowed(asset.assetId, workspaceId);
         const nowIso = new Date().toISOString();
         const purgeAfter = new Date(Date.now() + documentRetentionDays * 24 * 60 * 60 * 1000).toISOString();
         const metadata = markAssetDeleted(asset.storageKey);
@@ -987,55 +1160,49 @@ export function registerDocumentRoutes(deps) {
         }));
     });
     addRoute('PATCH', '/api/taskforce/documents/:assetId', async (req, res, params) => {
-        const workspaceId = requestWorkspaceId(req);
+        const workspaceId = requestWorkspaceIdWithQuery(req);
         const assetId = String(params.assetId || '').trim();
         const body = await parseJsonBody(req);
-        const displayName = String(body?.displayName || '').trim();
+        const title = String(body?.title || '').trim();
         if (!workspaceAssetStore || !assetId) {
             res.writeHead(404, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Document not found' }));
             return;
         }
-        if (!displayName) {
+        if (!title) {
             res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'displayName is required' }));
+            res.end(JSON.stringify({ error: 'title is required' }));
             return;
         }
-        const asset = workspaceAssetStore.get(assetId, workspaceId);
-        if (!asset || asset.kind !== 'document' || asset.deletedAt) {
+        const asset = workspaceAssetStore.getDocument(assetId, workspaceId);
+        if (!asset || asset.deletedAt) {
             res.writeHead(404, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Document not found' }));
             return;
         }
+        if (!ensureWorkspaceAssetAccess(req, res, {
+            operation: 'write',
+            asset,
+            fallbackWorkspaceId: workspaceId
+        }).allowed)
+            return;
         const updatedAt = new Date().toISOString();
-        const updated = workspaceAssetStore.upsertAsset({
+        const updated = workspaceAssetStore.renameDocumentTitle({
             assetId: asset.assetId,
             workspaceId,
-            kind: asset.kind,
-            logicalName: displayName,
-            originalFilename: asset.originalFilename,
-            mimeType: asset.mimeType,
-            storageProvider: asset.storageProvider,
-            storageKey: asset.storageKey,
-            contentSha256: asset.contentSha256,
-            sizeBytes: asset.sizeBytes,
-            documentId: asset.documentId,
-            version: asset.version,
-            isLatest: asset.isLatest,
-            scanStatus: asset.scanStatus,
-            scanEngine: asset.scanEngine,
-            scanDetails: asset.scanDetails,
-            createdByUserId: asset.createdByUserId,
-            createdAt: asset.createdAt,
+            title,
             updatedAt,
-            deletedAt: null,
-            purgeAfter: asset.purgeAfter
         });
+        if (!updated) {
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Document title could not be updated.' }));
+            return;
+        }
         res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ success: true, assetId: updated.assetId, displayName: updated.logicalName, updatedAt }));
+        res.end(JSON.stringify({ success: true, assetId: updated.assetId, title: updated.title, updatedAt }));
     });
     addRoute('POST', '/api/taskforce/documents/save', async (req, res) => {
-        const workspaceId = requestWorkspaceId(req);
+        const workspaceId = requestWorkspaceIdWithQuery(req);
         const { projectRoot, basePath } = core.getPaths();
         const objectStorageClient = getObjectStorageClient();
         const MAX_BODY_BYTES = 1_048_576;
@@ -1079,6 +1246,14 @@ export function registerDocumentRoutes(deps) {
         const normalizedStoragePath = normalizeTaskDataRelativePath(fsPath.replace(/^\.taskforce[\\/]+/, '').replace(/\\/g, '/'));
         if (normalizedStoragePath) {
             const metadata = getAssetMetadata(normalizedStoragePath);
+            const canonicalAsset = getCanonicalAssetMetadata(normalizedStoragePath);
+            if (!ensureWorkspaceAssetAccess(req, res, {
+                operation: 'write',
+                asset: canonicalAsset,
+                storageKey: normalizedStoragePath,
+                fallbackWorkspaceId: metadata?.workspaceId
+            }).allowed)
+                return;
             if (metadata?.quarantineStatus === 'quarantined') {
                 res.writeHead(423, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Document is quarantined and cannot be edited.' }));
@@ -1090,9 +1265,8 @@ export function registerDocumentRoutes(deps) {
                 return;
             }
             if (objectStorageClient && metadata?.provider === 'r2') {
-                const requestWorkspace = requestWorkspaceId(req);
                 const assetWorkspaceId = String(metadata.workspaceId || inferWorkspaceIdFromStoragePath(normalizedStoragePath) || 'default').trim() || 'default';
-                if (requestWorkspace !== assetWorkspaceId) {
+                if (workspaceId !== assetWorkspaceId) {
                     res.writeHead(403, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: 'Document belongs to a different workspace.' }));
                     return;
@@ -1109,8 +1283,11 @@ export function registerDocumentRoutes(deps) {
                         originalName: metadata.logicalName || metadata.originalFilename || path.basename(normalizedStoragePath)
                     });
                     clearAssetDeleted(normalizedStoragePath);
+                    const version = workspaceAssetStore
+                        ?.getByStorageKey(normalizedStoragePath, assetWorkspaceId)
+                        ?.version ?? null;
                     res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ success: true, updatedAt: new Date().toISOString() }));
+                    res.end(JSON.stringify({ success: true, updatedAt: new Date().toISOString(), version }));
                     return;
                 }
                 catch (e) {
@@ -1150,19 +1327,24 @@ export function registerDocumentRoutes(deps) {
         try {
             fs.writeFileSync(realPath, content, 'utf-8');
             const updatedAt = fs.statSync(realPath).mtime.toISOString();
+            let version = null;
             if (normalizedStoragePath) {
+                const assetWorkspaceId = workspaceId || inferWorkspaceIdFromStoragePath(normalizedStoragePath);
                 await scanAndRecordDocument({
                     relativeToStorage: normalizedStoragePath,
                     buffer: Buffer.from(content, 'utf8'),
                     contentType: 'text/markdown; charset=utf-8',
                     provider: 'local',
-                    workspaceId: workspaceId || inferWorkspaceIdFromStoragePath(normalizedStoragePath),
+                    workspaceId: assetWorkspaceId,
                     originalName: path.basename(normalizedStoragePath)
                 });
                 clearAssetDeleted(normalizedStoragePath);
+                version = workspaceAssetStore
+                    ?.getByStorageKey(normalizedStoragePath, assetWorkspaceId)
+                    ?.version ?? null;
             }
             res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: true, updatedAt }));
+            res.end(JSON.stringify({ success: true, updatedAt, version }));
         }
         catch (e) {
             res.writeHead(500, { 'Content-Type': 'application/json' });
@@ -1211,7 +1393,7 @@ export function registerDocumentRoutes(deps) {
         res.end(JSON.stringify({ tasks }));
     });
     addRoute('POST', '/api/taskforce/documents/generate-tasks/commit', async (req, res) => {
-        const workspaceId = requestWorkspaceId(req);
+        const workspaceId = requestWorkspaceIdWithQuery(req);
         const MAX_COMMIT_BYTES = 524_288;
         const MAX_TASKS = 200;
         const MAX_TITLE_LENGTH = 200;
@@ -1258,40 +1440,52 @@ export function registerDocumentRoutes(deps) {
                 .trim()
                 .slice(0, MAX_TITLE_LENGTH) || 'Untitled task';
         }
-        const created = [];
-        let totalCreated = 0;
-        function createSelectedTasks(nodes, depth) {
+        const candidates = [];
+        function collectSelectedTasks(nodes, depth) {
             if (depth > MAX_DEPTH)
                 return;
             for (const node of nodes) {
                 if (Array.isArray(node.children) && node.children.length > 0) {
-                    createSelectedTasks(node.children, depth + 1);
+                    collectSelectedTasks(node.children, depth + 1);
                 }
                 if (!node.selected)
                     continue;
-                if (totalCreated >= MAX_TASKS)
+                if (candidates.length >= MAX_TASKS)
                     break;
-                try {
-                    const taskItem = core.createTask({
-                        title: sanitiseTitle(node.title),
-                        description: String(node.description || '').slice(0, 2000).trim() || undefined,
-                        type: node.type || 'feature',
-                        priority: typeof node.priority === 'number' ? node.priority : 2,
-                        status: 'task',
-                    }, {
-                        workspaceId,
-                        provisionalLocalReference: shouldUseProvisionalTaskReferences(requestRuntimeMode(req))
-                    });
-                    created.push(taskItem.id);
-                    totalCreated++;
-                }
-                catch {
-                    // Skip individual failures and return a partial success summary.
-                }
+                candidates.push({
+                    title: sanitiseTitle(node.title),
+                    description: String(node.description || '').slice(0, 2000).trim() || undefined,
+                    type: node.type || 'feature',
+                    priority: typeof node.priority === 'number' ? node.priority : 2,
+                    status: 'task',
+                });
             }
         }
-        createSelectedTasks(tasks, 0);
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ created: created.length, taskIds: created }));
+        collectSelectedTasks(tasks, 0);
+        try {
+            const routers = createTaskHttpDurableRouters({ core, context, req, workspaceId });
+            const created = routers.root.enabled
+                ? routers.bulk.create(candidates, false, 'document-generate-tasks').created
+                : candidates.flatMap((candidate) => {
+                    try {
+                        return [core.createTask(candidate, {
+                                workspaceId,
+                                provisionalLocalReference: shouldUseProvisionalTaskReferences(requestRuntimeMode(req))
+                            })];
+                    }
+                    catch {
+                        return [];
+                    }
+                });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ created: created.length, taskIds: created.map((task) => task.id) }));
+        }
+        catch (error) {
+            res.writeHead(resolveErrorStatusCode(error, 400), { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: error instanceof Error ? error.message : 'Failed to generate tasks.',
+                ...(error?.code ? { code: String(error.code) } : {}),
+            }));
+        }
     });
 }