@taskforcehq/taskforce 0.3.327 → 0.3.329

package/dist/server/routes/tasks.js

@@ -57,7 +57,7 @@ import { resolveBuildInfo } from '../buildInfo.js';
 import { resolveRealtimeSyncFlag } from '../../sync/realtimeFeature.js';
 import { parseJsonBody } from './primitives.js';
 import { resolveRequestAccess } from '../auth.js';
-import { getRouteTimingNow, logSlowBootstrapRoute, requestBootstrapTraceId, requestHeader, requestRuntimeMode, requestUserId, resolveErrorStatusCode, serializeJsonWithTiming, setServerTimingHeader } from './shared.js';
+import { currentPerformanceTraceDiagnostics, getRouteTimingNow, logSlowBootstrapRoute, performanceTraceServerTimingMetrics, requestBootstrapTraceId, requestHeader, requestHumanActorRef, requestRuntimeMode, respondWithPerformanceTraceJson, resolveErrorStatusCode, runWithPerformanceTrace, serializeJsonWithTiming, setPerformanceTraceHeaders, setServerTimingHeader } from './shared.js';
 import { listBuiltInCustomTaxonomyLibraryPacks } from '../../shared/customTaxonomyLibrary.js';
 import { getBuiltInTaxonomyLibraryPack, listBuiltInTaxonomyLibraryPacks } from '../../shared/taxonomyLibrary.js';
 import { shouldUseProvisionalTaskReferences } from '../../utils/taskReferences.js';
@@ -177,7 +177,7 @@ export function registerTaskRoutes(deps) {
             surface: 'http',
             tenantId: core.getTenantId(),
             workspaceId,
-            actorRef: runtimeMode === 'cloud' ? (String(requestUserId(req) || '').trim() || 'user') : 'user',
+            actorRef: requestHumanActorRef(req),
             cloudClientId: 'http-cloud',
             ...(operationId ? { createOperationId: () => operationId } : {}),
         });
@@ -192,7 +192,7 @@ export function registerTaskRoutes(deps) {
             surface: 'http',
             tenantId: core.getTenantId(),
             workspaceId,
-            actorRef: runtimeMode === 'cloud' ? (String(requestUserId(req) || '').trim() || 'user') : 'user',
+            actorRef: requestHumanActorRef(req),
             cloudClientId: 'http-cloud',
             ...(operationId ? { createOperationId: () => operationId } : {}),
         });
@@ -465,9 +465,70 @@ export function registerTaskRoutes(deps) {
         if (!ensureAppAccess(req, res))
             return;
         const workspaceId = requestWorkspaceId(req);
-        const data = core.listTasks(workspaceId);
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify(data));
+        respondWithPerformanceTraceJson({
+            req,
+            res,
+            route: '/api/taskforce/tasks',
+            workspaceId,
+            // Local V2 sync still builds an outbound snapshot from these collections.
+            // Keep its full graph until that writer is retired; cloud is read-authoritative.
+            load: () => (context.authConfig?.runtimeMode === 'cloud' ? 'cloud' : requestRuntimeMode(req)) === 'cloud'
+                ? core.listActiveTaskSummaries(workspaceId)
+                : core.listTasks(workspaceId),
+        });
+    });
+    // GET /api/taskforce/tasks/search - Search lightweight task summaries across lifecycles
+    addRoute('GET', '/api/taskforce/tasks/search', async (req, res) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        try {
+            const requestUrl = new URL(req.url || '', 'http://localhost');
+            const query = String(requestUrl.searchParams.get('query') || '').trim();
+            if (!query) {
+                throw new TaskforceRuleError('query is required.', 400, 'TASK_SEARCH_QUERY_REQUIRED');
+            }
+            if (query.length > 200) {
+                throw new TaskforceRuleError('query must be 200 characters or fewer.', 400, 'TASK_SEARCH_QUERY_TOO_LONG');
+            }
+            const scopeInput = String(requestUrl.searchParams.get('scope') || 'all').trim();
+            if (!['all', 'active', 'archive'].includes(scopeInput)) {
+                throw new TaskforceRuleError('scope must be all, active, or archive.', 400, 'TASK_SEARCH_SCOPE_INVALID');
+            }
+            const parseBoundedInteger = (name, fallback, max) => {
+                const raw = requestUrl.searchParams.get(name);
+                if (raw === null || raw === '')
+                    return fallback;
+                const parsed = Number(raw);
+                if (!Number.isInteger(parsed) || parsed < (name === 'limit' ? 1 : 0) || parsed > max) {
+                    throw new TaskforceRuleError(`${name} must be an integer between ${name === 'limit' ? 1 : 0} and ${max}.`, 400, `TASK_SEARCH_${name.toUpperCase()}_INVALID`);
+                }
+                return parsed;
+            };
+            const limit = parseBoundedInteger('limit', 50, 50);
+            const offset = parseBoundedInteger('offset', 0, 10_000);
+            const workspaceId = requestWorkspaceId(req);
+            const rows = core.searchTaskSummaries(query, scopeInput, workspaceId, { limit: limit + 1, offset });
+            const hasMore = rows.length > limit;
+            const matches = rows.slice(0, limit);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                matches,
+                pagination: {
+                    limit,
+                    offset,
+                    returned: matches.length,
+                    hasMore,
+                    nextOffset: hasMore ? offset + matches.length : null,
+                },
+            }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            const message = error instanceof Error ? error.message : 'Failed to search tasks.';
+            const code = error instanceof TaskforceRuleError ? error.code : error?.code;
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: message, code }));
+        }
     });
     addRoute('GET', '/api/taskforce/task-relationships', async (req, res) => {
         if (!ensureAppAccess(req, res))
@@ -480,9 +541,13 @@ export function registerTaskRoutes(deps) {
         if (!ensureAppAccess(req, res))
             return;
         const workspaceId = requestWorkspaceId(req);
-        const data = core.listDeletedTasks(workspaceId);
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify(data));
+        respondWithPerformanceTraceJson({
+            req,
+            res,
+            route: '/api/taskforce/deleted',
+            workspaceId,
+            load: () => core.listDeletedTasks(workspaceId),
+        });
     };
     // GET /api/taskforce/deleted - List deleted tasks
     addRoute('GET', '/api/taskforce/deleted', handleListDeletedTasks);
@@ -589,7 +654,7 @@ export function registerTaskRoutes(deps) {
             const durableRouter = createTaskHttpRootRouter(req, workspaceId);
             const task = durableRouter.enabled ? durableRouter.create(taskInput) : core.createTask(taskInput, {
                 workspaceId,
-                actorRef: 'user',
+                actorRef: requestHumanActorRef(req),
                 provisionalLocalReference: shouldUseProvisionalTaskReferences(requestRuntimeMode(req))
             });
             res.writeHead(201, { 'Content-Type': 'application/json' });
@@ -609,6 +674,20 @@ export function registerTaskRoutes(deps) {
             }));
         }
     });
+    // GET /api/taskforce/task/:id - Read complete active or archived task detail
+    addRoute('GET', '/api/taskforce/task/:id', async (req, res, params) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const workspaceId = requestWorkspaceId(req);
+        const task = core.getTaskDetailSnapshot(params.id, workspaceId);
+        if (!task) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Task not found' }));
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(task));
+    });
     // PATCH /api/taskforce/task/:id - Update a task
     addRoute('PATCH', '/api/taskforce/task/:id', async (req, res, params) => {
         if (!ensureAppAccess(req, res))
@@ -617,8 +696,15 @@ export function registerTaskRoutes(deps) {
         try {
             const workspaceId = requestWorkspaceId(req);
             const saveSource = body?.saveSource === 'autosave' ? 'autosave' : 'manual';
+            const expectedDetailRevision = typeof body?.expectedDetailRevision === 'string'
+                ? body.expectedDetailRevision.trim()
+                : null;
+            if (body && Object.prototype.hasOwnProperty.call(body, 'expectedDetailRevision')
+                && !expectedDetailRevision) {
+                throw new TaskforceRuleError('expectedDetailRevision must be a non-empty string.', 400, 'TASK_DETAIL_REVISION_INVALID');
+            }
             const updates = body && typeof body === 'object'
-                ? Object.fromEntries(Object.entries(body).filter(([key]) => key !== 'saveSource'))
+                ? Object.fromEntries(Object.entries(body).filter(([key]) => (key !== 'saveSource' && key !== 'expectedDetailRevision')))
                 : body;
             const durableRouters = createTaskHttpDurableRouters({ core, context, req, workspaceId });
             const durableRouter = durableRouters.root;
@@ -630,22 +716,34 @@ export function registerTaskRoutes(deps) {
             if (hasAttachments && !Array.isArray(updates.attachments)) {
                 throw new TaskforceRuleError('attachments must be an array.', 400, 'TASK_ATTACHMENT_LINKS_INVALID');
             }
+            const hasCardCover = Object.prototype.hasOwnProperty.call(updates || {}, 'cardCoverAssetId');
+            if (hasCardCover && updates.cardCoverAssetId !== null
+                && (typeof updates.cardCoverAssetId !== 'string' || !updates.cardCoverAssetId.trim())) {
+                throw new TaskforceRuleError('cardCoverAssetId must be a non-empty string or null.', 400, 'TASK_CARD_COVER_INVALID');
+            }
             const checklistDurable = hasChecklist && durableRouters.checklist.enabled;
-            const attachmentLinksDurable = hasAttachments && durableRouters.attachmentLinks.enabled;
+            const attachmentLinksDurable = (hasAttachments || hasCardCover) && durableRouters.attachmentLinks.enabled;
             const rawChecklistItems = hasChecklist ? updates.checklistItems : [];
-            const rawAttachments = hasAttachments ? updates.attachments : [];
+            const rawAttachments = hasAttachments
+                ? updates.attachments
+                : (core.getTask(params.id, workspaceId)?.attachments || []);
             const remainingUpdates = checklistDurable || attachmentLinksDurable
                 ? Object.fromEntries(Object.entries(updates).filter(([key]) => (!(checklistDurable && key === 'checklistItems')
-                    && !(attachmentLinksDurable && key === 'attachments'))))
+                    && !(attachmentLinksDurable && key === 'attachments')
+                    && !(attachmentLinksDurable && key === 'cardCoverAssetId'))))
                 : updates;
             let updated;
             const durableTargetCount = Number(checklistDurable)
                 + Number(attachmentLinksDurable)
                 + Number(Object.keys(remainingUpdates).length > 0);
-            if (durableTargetCount > 1) {
+            if (durableTargetCount > 1 || Boolean(expectedDetailRevision && (checklistDurable || attachmentLinksDurable))) {
                 const aggregate = durableRouters.bulk.updateFields([
                     { id: params.id, ...updates },
-                ], { saveSource, atomicItemFailures: true });
+                ], {
+                    saveSource,
+                    atomicItemFailures: true,
+                    ...(expectedDetailRevision ? { expectedDetailRevision } : {}),
+                });
                 const failure = aggregate.errors[0];
                 if (failure) {
                     throw new TaskforceRuleError(failure.message, failure.statusCode, failure.code || 'TASK_UPDATE_FAILED', failure.details);
@@ -655,11 +753,13 @@ export function registerTaskRoutes(deps) {
             else {
                 updated = Object.keys(remainingUpdates || {}).length > 0
                     ? (durableRouter.enabled
-                        ? durableRouter.update(params.id, remainingUpdates, saveSource)
-                        : core.updateTask(params.id, remainingUpdates, workspaceId, {
-                            actorRef: 'user',
-                            saveSource,
-                        }))
+                        ? durableRouter.update(params.id, remainingUpdates, saveSource, undefined, expectedDetailRevision || undefined)
+                        : expectedDetailRevision !== null
+                            ? core.updateTaskIfDetailRevisionMatches(params.id, expectedDetailRevision, remainingUpdates, workspaceId, { actorRef: requestHumanActorRef(req), saveSource })
+                            : core.updateTask(params.id, remainingUpdates, workspaceId, {
+                                actorRef: requestHumanActorRef(req),
+                                saveSource,
+                            }))
                     : core.getTask(params.id, workspaceId);
                 if (updated && checklistDurable) {
                     const checklistRouter = durableRouters.createChecklistRouter(durableRouters.deriveChildOperationId('task-patch-checklist', 0, params.id));
@@ -679,7 +779,15 @@ export function registerTaskRoutes(deps) {
                         core,
                         workspaceId,
                     });
-                    updated = attachmentLinksRouter.replace({ taskId: params.id, links }).task;
+                    updated = attachmentLinksRouter.replace({
+                        taskId: params.id,
+                        links,
+                        ...(hasCardCover ? {
+                            cardCoverAssetId: updates.cardCoverAssetId === null
+                                ? null
+                                : String(updates.cardCoverAssetId).trim(),
+                        } : {}),
+                    }).task;
                 }
             }
             if (!updated) {
@@ -687,8 +795,14 @@ export function registerTaskRoutes(deps) {
                 res.end(JSON.stringify({ error: 'Task not found' }));
                 return;
             }
+            const authoritative = core.getTaskDetailSnapshot(params.id, workspaceId);
+            if (!authoritative) {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Task not found' }));
+                return;
+            }
             res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify(updated));
+            res.end(JSON.stringify(authoritative));
         }
         catch (error) {
             const statusCode = resolveErrorStatusCode(error, 400);
@@ -766,43 +880,53 @@ export function registerTaskRoutes(deps) {
     addRoute('GET', '/api/taskforce/planning/bootstrap', async (req, res) => {
         if (!ensureAppAccess(req, res))
             return;
-        const startedAt = getRouteTimingNow();
-        const workspaceId = requestWorkspaceId(req);
-        const traceId = requestBootstrapTraceId(req);
-        const diagnostics = {};
-        const data = core.listPlanningBootstrap(workspaceId, diagnostics);
-        const serializeStartedAt = getRouteTimingNow();
-        const serialized = serializeJsonWithTiming(data, serializeStartedAt);
-        const totalDurationMs = Math.max(0, getRouteTimingNow() - startedAt);
-        const details = diagnostics;
-        setServerTimingHeader(res, [
-            { name: 'planning-bootstrap', durationMs: totalDurationMs },
-            { name: 'planning-bootstrap-initiatives', durationMs: details.initiativeLoadMs ?? 0 },
-            { name: 'planning-bootstrap-workstreams', durationMs: details.workstreamLoadMs ?? 0 },
-            { name: 'planning-bootstrap-tasks', durationMs: details.taskSummaryQueryMs ?? 0 },
-            { name: 'planning-bootstrap-build', durationMs: details.taskSummaryBuildMs ?? 0 },
-            { name: 'planning-bootstrap-json', durationMs: serialized.durationMs },
-        ]);
-        logSlowBootstrapRoute({
-            route: '/api/taskforce/planning/bootstrap',
-            workspaceId,
-            traceId,
-            durationMs: totalDurationMs,
-            details: {
-                initiativeCount: details.initiativeCount ?? 0,
-                workstreamCount: details.workstreamCount ?? 0,
-                workstreamLinkedTaskCount: details.workstreamLinkedTaskCount ?? 0,
-                workstreamTaskSummaryCount: details.workstreamTaskSummaryCount ?? 0,
-                responseBytes: serialized.byteLength,
-                initiativeLoadMs: details.initiativeLoadMs ?? 0,
-                workstreamLoadMs: details.workstreamLoadMs ?? 0,
-                taskSummaryQueryMs: details.taskSummaryQueryMs ?? 0,
-                taskSummaryBuildMs: details.taskSummaryBuildMs ?? 0,
-                jsonSerializeMs: serialized.durationMs,
-            },
+        runWithPerformanceTrace(req, () => {
+            const startedAt = getRouteTimingNow();
+            const workspaceId = requestWorkspaceId(req);
+            const traceId = requestBootstrapTraceId(req);
+            const diagnostics = {};
+            const data = core.listPlanningBootstrap(workspaceId, diagnostics);
+            const serializeStartedAt = getRouteTimingNow();
+            const serialized = serializeJsonWithTiming(data, serializeStartedAt);
+            const totalDurationMs = Math.max(0, getRouteTimingNow() - startedAt);
+            const details = diagnostics;
+            const performanceDiagnostics = currentPerformanceTraceDiagnostics();
+            setServerTimingHeader(res, [
+                { name: 'planning-bootstrap', durationMs: totalDurationMs },
+                { name: 'planning-bootstrap-initiatives', durationMs: details.initiativeLoadMs ?? 0 },
+                { name: 'planning-bootstrap-workstreams', durationMs: details.workstreamLoadMs ?? 0 },
+                { name: 'planning-bootstrap-tasks', durationMs: details.taskSummaryQueryMs ?? 0 },
+                { name: 'planning-bootstrap-build', durationMs: details.taskSummaryBuildMs ?? 0 },
+                { name: 'planning-bootstrap-json', durationMs: serialized.durationMs },
+                ...performanceTraceServerTimingMetrics(performanceDiagnostics),
+            ]);
+            setPerformanceTraceHeaders(res, performanceDiagnostics, serialized.byteLength);
+            logSlowBootstrapRoute({
+                route: '/api/taskforce/planning/bootstrap',
+                workspaceId,
+                traceId,
+                durationMs: totalDurationMs,
+                details: {
+                    initiativeCount: details.initiativeCount ?? 0,
+                    workstreamCount: details.workstreamCount ?? 0,
+                    workstreamLinkedTaskCount: details.workstreamLinkedTaskCount ?? 0,
+                    workstreamTaskSummaryCount: details.workstreamTaskSummaryCount ?? 0,
+                    responseBytes: serialized.byteLength,
+                    initiativeLoadMs: details.initiativeLoadMs ?? 0,
+                    workstreamLoadMs: details.workstreamLoadMs ?? 0,
+                    taskSummaryQueryMs: details.taskSummaryQueryMs ?? 0,
+                    taskSummaryBuildMs: details.taskSummaryBuildMs ?? 0,
+                    jsonSerializeMs: serialized.durationMs,
+                    ...(performanceDiagnostics ? {
+                        postgresQueryCount: performanceDiagnostics.postgresQueryCount,
+                        postgresWorkerCallCount: performanceDiagnostics.postgresWorkerCallCount,
+                        postgresWorkerWaitMs: Math.round(performanceDiagnostics.postgresWorkerWaitMs),
+                    } : {}),
+                },
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(serialized.body);
         });
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(serialized.body);
     });
     // POST /api/taskforce/initiative - Create initiative
     addRoute('POST', '/api/taskforce/initiative', async (req, res) => {
@@ -812,7 +936,7 @@ export function registerTaskRoutes(deps) {
         try {
             const workspaceId = requestWorkspaceId(req);
             const router = createInitiativeRouter(req, workspaceId);
-            const allowed = new Set(['id', 'title', 'description', 'ownerId', 'order', 'attachments', 'createdAt']);
+            const allowed = new Set(['id', 'title', 'description', 'ownerId', 'order', 'attachments', 'createdAt', 'icon', 'color']);
             const unsupported = Object.keys(body || {}).filter((key) => !allowed.has(key));
             if (router.enabled && unsupported.length > 0) {
                 const error = new Error(`Unsupported initiative fields: ${unsupported.sort().join(', ')}`);
@@ -826,16 +950,28 @@ export function registerTaskRoutes(deps) {
                 error.statusCode = 400;
                 throw error;
             }
-            const initiative = router.enabled
-                ? initiativeResult(router.create(String(body?.id || '').trim() || `initiative-${randomUUID()}`, {
-                    title: body?.title,
-                    description: body?.description ?? null,
-                    ownerId: body?.ownerId ?? null,
-                    order: body?.order ?? null,
-                    attachments: serializeCanonicalPlanningAttachmentLinks(body?.attachments ?? []),
-                    createdAt: String(body?.createdAt || '').trim() || new Date().toISOString(),
-                }))
-                : core.createInitiative(body || {}, workspaceId, { actorRef: 'user' });
+            const initiative = core.getDatabaseAdapter().transaction(() => {
+                const created = router.enabled
+                    ? initiativeResult(router.create(String(body?.id || '').trim() || `initiative-${randomUUID()}`, {
+                        title: body?.title,
+                        description: body?.description ?? null,
+                        ownerId: body?.ownerId ?? null,
+                        order: body?.order ?? null,
+                        attachments: serializeCanonicalPlanningAttachmentLinks(body?.attachments ?? []),
+                        createdAt: String(body?.createdAt || '').trim() || new Date().toISOString(),
+                    }))
+                    : core.createInitiative(body || {}, workspaceId, { actorRef: requestHumanActorRef(req) });
+                if (!created)
+                    throw new Error('Durable initiative capture did not return a provisional initiative.');
+                const hasIdentity = Object.prototype.hasOwnProperty.call(body || {}, 'icon')
+                    || Object.prototype.hasOwnProperty.call(body || {}, 'color');
+                return hasIdentity
+                    ? core.updatePlanningEntityIdentity('initiative', created.id, {
+                        ...(Object.prototype.hasOwnProperty.call(body || {}, 'icon') ? { icon: body.icon } : {}),
+                        ...(Object.prototype.hasOwnProperty.call(body || {}, 'color') ? { color: body.color } : {}),
+                    }, workspaceId)
+                    : created;
+            })();
             if (!initiative)
                 throw new Error('Durable initiative capture did not return a provisional initiative.');
             res.writeHead(201, { 'Content-Type': 'application/json' });
@@ -883,7 +1019,7 @@ export function registerTaskRoutes(deps) {
             };
             const updated = router.enabled
                 ? initiativeResult(router.updateMetadata(params.id, durablePatch))
-                : core.updateInitiative(params.id, body || {}, workspaceId, { actorRef: 'user' });
+                : core.updateInitiative(params.id, body || {}, workspaceId, { actorRef: requestHumanActorRef(req) });
             if (!updated)
                 throw new Error('Durable initiative capture did not return a provisional initiative.');
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -893,6 +1029,30 @@ export function registerTaskRoutes(deps) {
             writeInitiativeMutationError(res, error, 'Failed to update initiative');
         }
     });
+    addRoute('PATCH', '/api/taskforce/initiative/:id/identity', async (req, res, params) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const body = await parseJsonBody(req);
+        try {
+            const workspaceId = requestWorkspaceId(req);
+            const source = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+            const keys = Object.keys(source);
+            if (keys.length === 0 || keys.some((key) => key !== 'icon' && key !== 'color')) {
+                throw new TaskforceRuleError('Planning identity update must contain only icon or color.', 400, 'PLANNING_IDENTITY_INVALID');
+            }
+            const updated = core.updatePlanningEntityIdentity('initiative', params.id, source, workspaceId);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(updated));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: error instanceof Error ? error.message : 'Failed to update initiative identity',
+                code: error instanceof TaskforceRuleError ? error.code : undefined,
+            }));
+        }
+    });
     addRoute('POST', '/api/taskforce/initiative/:id/archive', async (req, res, params) => {
         if (!ensureAppAccess(req, res))
             return;
@@ -901,7 +1061,7 @@ export function registerTaskRoutes(deps) {
             const router = createInitiativeRouter(req, workspaceId);
             const archived = router.enabled
                 ? initiativeResult(router.archive(params.id))
-                : core.archiveInitiative(params.id, workspaceId, { actorRef: 'user' });
+                : core.archiveInitiative(params.id, workspaceId, { actorRef: requestHumanActorRef(req) });
             if (!archived)
                 throw new Error('Durable initiative capture did not return a provisional initiative.');
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -919,7 +1079,7 @@ export function registerTaskRoutes(deps) {
             const router = createInitiativeRouter(req, workspaceId);
             const restored = router.enabled
                 ? initiativeResult(router.unarchive(params.id))
-                : core.unarchiveInitiative(params.id, workspaceId, { actorRef: 'user' });
+                : core.unarchiveInitiative(params.id, workspaceId, { actorRef: requestHumanActorRef(req) });
             if (!restored)
                 throw new Error('Durable initiative capture did not return a provisional initiative.');
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -946,7 +1106,7 @@ export function registerTaskRoutes(deps) {
         try {
             const workspaceId = requestWorkspaceId(req);
             const router = createWorkstreamRouter(req, workspaceId);
-            const allowed = new Set(['id', 'initiativeId', 'title', 'description', 'ownerId', 'order', 'attachments', 'createdAt']);
+            const allowed = new Set(['id', 'initiativeId', 'title', 'description', 'ownerId', 'order', 'attachments', 'createdAt', 'icon', 'color']);
             const unsupported = Object.keys(body || {}).filter((key) => !allowed.has(key));
             if (router.enabled && unsupported.length > 0) {
                 const error = new Error(`Unsupported workstream fields: ${unsupported.sort().join(', ')}`);
@@ -960,17 +1120,29 @@ export function registerTaskRoutes(deps) {
                 error.statusCode = 400;
                 throw error;
             }
-            const workstream = router.enabled
-                ? workstreamResult(router.create(String(body?.id || '').trim(), {
-                    initiativeId: body?.initiativeId ?? null,
-                    title: body?.title,
-                    description: body?.description ?? null,
-                    ownerId: body?.ownerId ?? null,
-                    order: body?.order ?? null,
-                    attachments: serializeCanonicalPlanningAttachmentLinks(body?.attachments ?? []),
-                    createdAt: String(body?.createdAt || '').trim(),
-                }))
-                : core.createWorkstream(body || {}, workspaceId, { actorRef: 'user' });
+            const workstream = core.getDatabaseAdapter().transaction(() => {
+                const created = router.enabled
+                    ? workstreamResult(router.create(String(body?.id || '').trim(), {
+                        initiativeId: body?.initiativeId ?? null,
+                        title: body?.title,
+                        description: body?.description ?? null,
+                        ownerId: body?.ownerId ?? null,
+                        order: body?.order ?? null,
+                        attachments: serializeCanonicalPlanningAttachmentLinks(body?.attachments ?? []),
+                        createdAt: String(body?.createdAt || '').trim(),
+                    }))
+                    : core.createWorkstream(body || {}, workspaceId, { actorRef: requestHumanActorRef(req) });
+                if (!created)
+                    throw new Error('Durable workstream capture did not return a provisional workstream.');
+                const hasIdentity = Object.prototype.hasOwnProperty.call(body || {}, 'icon')
+                    || Object.prototype.hasOwnProperty.call(body || {}, 'color');
+                return hasIdentity
+                    ? core.updatePlanningEntityIdentity('workstream', created.id, {
+                        ...(Object.prototype.hasOwnProperty.call(body || {}, 'icon') ? { icon: body.icon } : {}),
+                        ...(Object.prototype.hasOwnProperty.call(body || {}, 'color') ? { color: body.color } : {}),
+                    }, workspaceId)
+                    : created;
+            })();
             if (!workstream)
                 throw new Error('Durable workstream capture did not return a provisional workstream.');
             res.writeHead(201, { 'Content-Type': 'application/json' });
@@ -1018,7 +1190,7 @@ export function registerTaskRoutes(deps) {
             };
             const updated = router.enabled
                 ? workstreamResult(router.updateMetadata(params.id, durablePatch))
-                : core.updateWorkstream(params.id, body || {}, workspaceId, { actorRef: 'user' });
+                : core.updateWorkstream(params.id, body || {}, workspaceId, { actorRef: requestHumanActorRef(req) });
             if (!updated)
                 throw new Error('Durable workstream capture did not return a provisional workstream.');
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -1028,6 +1200,30 @@ export function registerTaskRoutes(deps) {
             writeWorkstreamMutationError(res, error, 'Failed to update workstream');
         }
     });
+    addRoute('PATCH', '/api/taskforce/workstream/:id/identity', async (req, res, params) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const body = await parseJsonBody(req);
+        try {
+            const workspaceId = requestWorkspaceId(req);
+            const source = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+            const keys = Object.keys(source);
+            if (keys.length === 0 || keys.some((key) => key !== 'icon' && key !== 'color')) {
+                throw new TaskforceRuleError('Planning identity update must contain only icon or color.', 400, 'PLANNING_IDENTITY_INVALID');
+            }
+            const updated = core.updatePlanningEntityIdentity('workstream', params.id, source, workspaceId);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(updated));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: error instanceof Error ? error.message : 'Failed to update workstream identity',
+                code: error instanceof TaskforceRuleError ? error.code : undefined,
+            }));
+        }
+    });
     addRoute('POST', '/api/taskforce/workstream/:id/archive', async (req, res, params) => {
         if (!ensureAppAccess(req, res))
             return;
@@ -1036,7 +1232,7 @@ export function registerTaskRoutes(deps) {
             const router = createWorkstreamRouter(req, workspaceId);
             const archived = router.enabled
                 ? workstreamResult(router.archive(params.id))
-                : core.archiveWorkstream(params.id, workspaceId, { actorRef: 'user' });
+                : core.archiveWorkstream(params.id, workspaceId, { actorRef: requestHumanActorRef(req) });
             if (!archived)
                 throw new Error('Durable workstream capture did not return a provisional workstream.');
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -1054,7 +1250,7 @@ export function registerTaskRoutes(deps) {
             const router = createWorkstreamRouter(req, workspaceId);
             const restored = router.enabled
                 ? workstreamResult(router.unarchive(params.id))
-                : core.unarchiveWorkstream(params.id, workspaceId, { actorRef: 'user' });
+                : core.unarchiveWorkstream(params.id, workspaceId, { actorRef: requestHumanActorRef(req) });
             if (!restored)
                 throw new Error('Durable workstream capture did not return a provisional workstream.');
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -1180,9 +1376,15 @@ export function registerTaskRoutes(deps) {
         if (!ensureAppAccess(req, res))
             return;
         const workspaceId = requestWorkspaceId(req);
-        const data = core.listArchive(workspaceId);
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify(data));
+        respondWithPerformanceTraceJson({
+            req,
+            res,
+            route: '/api/taskforce/archive',
+            workspaceId,
+            load: () => (context.authConfig?.runtimeMode === 'cloud' ? 'cloud' : requestRuntimeMode(req)) === 'cloud'
+                ? core.listArchiveSummaries(workspaceId)
+                : core.listArchive(workspaceId),
+        });
     });
     // POST /api/taskforce/task/:id/complete - Archive as complete
     addRoute('POST', '/api/taskforce/task/:id/complete', async (req, res, params) => {
@@ -1193,7 +1395,7 @@ export function registerTaskRoutes(deps) {
             const durableRouter = createTaskHttpRootRouter(req, workspaceId);
             const archived = durableRouter.enabled
                 ? durableRouter.archive(params.id, false, null)
-                : core.archiveTask(params.id, false, undefined, workspaceId, { actorRef: 'user' });
+                : core.archiveTask(params.id, false, undefined, workspaceId, { actorRef: requestHumanActorRef(req) });
             if (!archived) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Task not found' }));
@@ -1221,7 +1423,7 @@ export function registerTaskRoutes(deps) {
             const durableRouter = createTaskHttpRootRouter(req, workspaceId);
             const archived = durableRouter.enabled
                 ? durableRouter.archive(params.id, true, reason)
-                : core.archiveTask(params.id, true, reason, workspaceId, { actorRef: 'user' });
+                : core.archiveTask(params.id, true, reason, workspaceId, { actorRef: requestHumanActorRef(req) });
             if (!archived) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Task not found' }));
@@ -1247,7 +1449,7 @@ export function registerTaskRoutes(deps) {
             const durableRouter = createTaskHttpRootRouter(req, workspaceId);
             const deleted = durableRouter.enabled
                 ? durableRouter.delete(params.id)
-                : core.softDeleteTask(params.id, workspaceId, { actorRef: 'user', source: 'ui' });
+                : core.softDeleteTask(params.id, workspaceId, { actorRef: requestHumanActorRef(req), source: 'ui' });
             if (!deleted) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Task not found' }));
@@ -1272,7 +1474,7 @@ export function registerTaskRoutes(deps) {
             const durableRouter = createTaskHttpRootRouter(req, workspaceId);
             const restored = durableRouter.enabled
                 ? durableRouter.restore(params.id)
-                : core.restoreDeletedTask(params.id, workspaceId, { actorRef: 'user' });
+                : core.restoreDeletedTask(params.id, workspaceId, { actorRef: requestHumanActorRef(req) });
             if (!restored) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Deleted task not found' }));
@@ -1362,7 +1564,7 @@ export function registerTaskRoutes(deps) {
                                 continue;
                             }
                             const task = core.restoreDeletedTask(deletedRecordId, workspaceId, {
-                                actorRef: 'user',
+                                actorRef: requestHumanActorRef(req),
                                 restoreDestination,
                             });
                             if (!task) {
@@ -1533,7 +1735,7 @@ export function registerTaskRoutes(deps) {
             const durableRouter = createTaskHttpRootRouter(req, workspaceId);
             const restored = durableRouter.enabled
                 ? durableRouter.unarchive(params.id)
-                : core.unarchiveTask(params.id, workspaceId, { actorRef: 'user' });
+                : core.unarchiveTask(params.id, workspaceId, { actorRef: requestHumanActorRef(req) });
             if (!restored) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'Archived task not found' }));