@taskforcehq/taskforce 0.3.328 → 0.3.329

package/dist/server/routes/localService.js

@@ -186,6 +186,7 @@ export function registerLocalServiceRoutes(deps) {
             projectIdentity: context.projectIdentity,
             dataIdentity: context.ownershipKey,
             cloudTarget: context.cloudTarget,
+            runtimeContract: context.runtimeContract,
             transports: ['streamable-http'],
             health: {
                 lifecycle: context.sessions.state(),
@@ -281,6 +282,7 @@ export function registerLocalServiceRoutes(deps) {
             protocolVersion: context.protocolVersion,
             ownerPid: context.ownerPid,
             cloudTarget: context.cloudTarget,
+            runtimeContract: context.runtimeContract,
             sessions: context.sessions.list(),
             ...(context.diagnostics?.() || {}),
         });

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

@@ -5,6 +5,7 @@ import type { LocalSyncCoordinatorRouteServices } from '../../sync/coordinator/l
 import type { WorkspaceSyncServerDataServices } from '../../sync/engine/workspaceSyncServerDataServices.js';
 import type { LocalServiceSessionManager } from '../localServiceSessions.js';
 import type { LocalServiceCloudTarget } from '../../config/localServiceCloudTarget.js';
+import type { LocalServiceRuntimeContract } from '../../config/localServiceRuntimeContract.js';
 export interface LocalServiceRouteContext {
     generation: string;
     protocolVersion: string;
@@ -13,6 +14,7 @@ export interface LocalServiceRouteContext {
     bootstrapCapability: string;
     ownershipKey: string;
     cloudTarget: LocalServiceCloudTarget;
+    runtimeContract: LocalServiceRuntimeContract;
     projectIdentity: string;
     operationClientId: string;
     sessions: LocalServiceSessionManager;

package/dist/server/routes/syncAuxRoutes.js

@@ -50,8 +50,11 @@ export function registerWorkspaceSyncAuxRoutes({ addRoute, core, context, resolv
         res.end(JSON.stringify({ success: true }));
     });
     // POST /api/taskforce/sync/workspace/repair-startup - Auto-repair workspace asset/document
-    // metadata on workspace open. Safe fixups re-register metadata for local files and mark
-    // stale, unreferenced metadata deleted when the file is missing. Never deletes files.
+    // metadata on workspace open. Safe fixups re-register metadata for local files and clean up
+    // stale links. Does NOT tombstone metadata for files that appear missing locally — a single
+    // failed existence check at startup can mean the content is only temporarily unavailable
+    // (e.g. storage not yet mounted/synced), not deleted; that requires explicit admin
+    // confirmation via /api/taskforce/admin/workspace-repair/apply. Never deletes files.
     // Called once by the sync orchestrator when the workspace becomes active.
     addRoute('POST', '/api/taskforce/sync/workspace/repair-startup', async (req, res) => {
         const authConfig = context.authConfig;

package/dist/server/routes/syncPullApplyRoutes.js

@@ -1,7 +1,7 @@
 import { DEFAULT_WORKSPACE_PULL_PAGE_MAX_BYTES, buildWorkspacePullFeed, WorkspacePullEntryTooLargeError, } from '../../sync/workspacePullFeed.js';
 import { applyWorkspaceSyncLocalBatch } from '../../sync/engine/workspaceSyncEngineLocalApply.js';
 import { parseJsonBody } from './primitives.js';
-import { normalizeWorkspaceSyncV2ProjectionExclusions, parseWorkspaceSyncV2ProjectionExclusions, WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS, } from '../../sync/v3/workspaceSyncV2ProjectionExclusions.js';
+import { normalizeWorkspaceSyncV2ProjectionExclusions, parseWorkspaceSyncV2ProjectionExclusions, WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS, workspaceSyncV2ProjectionExclusionsEqual, } from '../../sync/v3/workspaceSyncV2ProjectionExclusions.js';
 import { resolveWorkspaceSyncV3AttestedV2Exclusions } from '../../sync/v3/workspaceSyncV3LegacyBoundaryAttestation.js';
 import { requireAuthenticatedSyncRequest, requireEnabledSyncAuth, resolveAuthorizedSyncWorkspace, } from './syncRouteGuards.js';
 import { completeLocalSyncBrowserPushEchoPermitGroup, createLocalSyncBrowserV2ApplyTransactionHooks, parseLocalSyncBrowserApplyPermitContext, resolveLocalSyncBrowserApplyPermitOperationClass, } from '../../sync/coordinator/localSyncBrowserApplyPermitContext.js';
@@ -301,7 +301,16 @@ export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context,
                 };
             }
             if (!change) {
-                missing.push(request);
+                missing.push({
+                    ...request,
+                    disposition: request.kind === 'asset'
+                        && 'assetId' in request
+                        && (!requestedAsset
+                            || requestedAsset.deletedAt
+                            || requestedAsset.storageProvider === 'external')
+                        ? 'terminal-unavailable'
+                        : 'retryable',
+                });
                 consumed += 1;
                 continue;
             }
@@ -554,6 +563,16 @@ export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context,
                 : null;
             let applyResult;
             if (permitContext && coordinatorServices && permitOperationClass === 'push') {
+                const attestedV2ExcludedProjections = v2ExcludedProjections.length > 0
+                    ? (() => {
+                        const attested = resolveWorkspaceSyncV3AttestedV2Exclusions({
+                            coverage: body?.combinedCoverage,
+                            excludedProjections: v2ExcludedProjections,
+                            runtimeMode: 'local',
+                        });
+                        return attested && workspaceSyncV2ProjectionExclusionsEqual(attested, v2ExcludedProjections) ? attested : null;
+                    })()
+                    : [];
                 applyResult = completeLocalSyncBrowserPushEchoPermitGroup({
                     services: coordinatorServices,
                     cookieHeader: req.headers.cookie,
@@ -567,13 +586,13 @@ export function registerWorkspacePullApplySyncRoutes({ addRoute, core, context,
                             || workspaceMembers !== undefined
                             || body?.bootstrapSnapshot !== undefined
                             || allowReferenceNumberReassignment
-                            || v2ExcludedProjections.length > 0) {
+                            || !attestedV2ExcludedProjections) {
                             throw new Error('Browser push echo apply accepts only authoritative task upserts.');
                         }
                         return dispatchWorkspaceSyncMetadataAtomically(workspaceId, incomingChanges, {
                             allowReferenceNumberReassignment: false,
                             coexistenceDirection: 'local-pull',
-                            v2ExcludedProjections: [],
+                            v2ExcludedProjections: attestedV2ExcludedProjections,
                         });
                     },
                 });

package/dist/server/routes/syncV3FeedRoutes.js

@@ -5,7 +5,7 @@ import { buildWorkspaceSyncV3InitiativeRepairPage, decodeWorkspaceSyncV3Initiati
 import { WORKSPACE_SYNC_V3_COVERAGE_PROFILE } from '../../sync/v3/workspaceSyncV3FeedProfile.js';
 import { isWorkspaceSyncV3InitiativeLegacyPushDisabled } from '../../sync/v3/planningActivation.js';
 import { WORKSPACE_SYNC_V3_COMBINED_COVERAGE_PROFILE } from '../../sync/v3/workspaceSyncV3CombinedCoverage.js';
-import { buildWorkspaceSyncV3CombinedRepairPage, decodeWorkspaceSyncV3CombinedRepairCursor, decodeWorkspaceSyncV3NestedRepairCursor, decodeWorkspaceSyncV3PlanningOrderRepairCursor, decodeWorkspaceSyncV3WorkflowRepairCursor, WorkspaceSyncV3CombinedRepairSnapshotUnavailableError, } from '../../sync/v3/workspaceSyncV3CombinedRepairMaterialization.js';
+import { buildWorkspaceSyncV3CombinedRepairPage, decodeWorkspaceSyncV3CombinedRepairCursor, decodeWorkspaceSyncV3NestedRepairCursor, decodeWorkspaceSyncV3PlanningOrderRepairCursor, decodeWorkspaceSyncV3TaskCoverRepairCursor, decodeWorkspaceSyncV3WorkflowRepairCursor, WorkspaceSyncV3CombinedRepairSnapshotUnavailableError, } from '../../sync/v3/workspaceSyncV3CombinedRepairMaterialization.js';
 import { isWorkspaceSyncV3CombinedLegacyFenceEnabled } from '../../sync/v3/workspaceSyncV2ProjectionExclusions.js';
 import { resolveCombinedFeedCapability } from '../../sync/v3/combinedFeedCapability.js';
 import { resolveWorkspaceSyncV3RegisteredCoverage } from '../../sync/v3/workspaceSyncV3CoverageRegistry.js';
@@ -21,6 +21,17 @@ function json(res, status, body) {
     res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
     res.end(JSON.stringify(body));
 }
+function decodeCombinedRepairCursorForContract(rawCursor, keyring, wire) {
+    if (wire.taskCoverProjectionRequired)
+        return decodeWorkspaceSyncV3TaskCoverRepairCursor(rawCursor, keyring);
+    if (wire.workflowWriterPrerequisitesRequired)
+        return decodeWorkspaceSyncV3WorkflowRepairCursor(rawCursor, keyring);
+    if (wire.planningOrderWriterPrerequisitesRequired)
+        return decodeWorkspaceSyncV3PlanningOrderRepairCursor(rawCursor, keyring);
+    if (wire.nestedWriterPrerequisitesRequired)
+        return decodeWorkspaceSyncV3NestedRepairCursor(rawCursor, keyring);
+    return decodeWorkspaceSyncV3CombinedRepairCursor(rawCursor, keyring);
+}
 function attestLegacyPushBoundary(body, boundary) {
     const attested = { ...body, ...boundary };
     const mutable = attested;
@@ -215,13 +226,7 @@ export function registerWorkspaceSyncV3FeedRoutes(input) {
                 return;
             }
             const rawCursor = String(url.searchParams.get('cursor') || '').trim();
-            const cursor = requestedWire.workflowWriterPrerequisitesRequired
-                ? decodeWorkspaceSyncV3WorkflowRepairCursor(rawCursor, keyring)
-                : requestedWire.planningOrderWriterPrerequisitesRequired
-                    ? decodeWorkspaceSyncV3PlanningOrderRepairCursor(rawCursor, keyring)
-                    : requestedWire.nestedWriterPrerequisitesRequired
-                        ? decodeWorkspaceSyncV3NestedRepairCursor(rawCursor, keyring)
-                        : decodeWorkspaceSyncV3CombinedRepairCursor(rawCursor, keyring);
+            const cursor = decodeCombinedRepairCursorForContract(rawCursor, keyring, requestedWire);
             if (rawCursor && !cursor) {
                 json(res, 400, { success: false, code: 'INVALID_SYNC_COMBINED_REPAIR_CURSOR', error: 'Invalid combined repair cursor.' });
                 return;
@@ -231,7 +236,8 @@ export function registerWorkspaceSyncV3FeedRoutes(input) {
                 cursorKeyring: keyring, cursor, pageSize: Number.isFinite(limit) ? limit : undefined,
                 nestedCoverage: requestedWire.nestedWriterPrerequisitesRequired,
                 workflowCoverage: requestedWire.workflowWriterPrerequisitesRequired,
-                planningOrderCoverage: requestedWire.planningOrderWriterPrerequisitesRequired });
+                planningOrderCoverage: requestedWire.planningOrderWriterPrerequisitesRequired,
+                taskCoverCoverage: requestedWire.taskCoverProjectionRequired });
             json(res, 200, attestLegacyPushBoundary({ ...page }, {
                 contractVersion: 3,
                 legacyV2Boundary: { cloudWritesFenced: false, excludedProjections: [] },
@@ -328,13 +334,7 @@ export function registerWorkspaceSyncV3FeedRoutes(input) {
             return;
         }
         const repairCursor = coverage.kind === 'combined'
-            ? (coverage.wire.workflowWriterPrerequisitesRequired
-                ? decodeWorkspaceSyncV3WorkflowRepairCursor(rawRepairCursor, cursorKeyring)
-                : coverage.wire.planningOrderWriterPrerequisitesRequired
-                    ? decodeWorkspaceSyncV3PlanningOrderRepairCursor(rawRepairCursor, cursorKeyring)
-                    : coverage.wire.nestedWriterPrerequisitesRequired
-                        ? decodeWorkspaceSyncV3NestedRepairCursor(rawRepairCursor, cursorKeyring)
-                        : decodeWorkspaceSyncV3CombinedRepairCursor(rawRepairCursor, cursorKeyring))
+            ? decodeCombinedRepairCursorForContract(rawRepairCursor, cursorKeyring, coverage.wire)
             : decodeWorkspaceSyncV3InitiativeRepairCursor(rawRepairCursor, cursorKeyring);
         if (rawRepairCursor && (!repairEnabled || !repairCursor)) {
             json(res, 400, { success: false, code: 'INVALID_SYNC_V3_REPAIR_CURSOR', error: 'Invalid repair cursor.' });
@@ -353,6 +353,7 @@ export function registerWorkspaceSyncV3FeedRoutes(input) {
                         nestedCoverage: coverage.wire.nestedWriterPrerequisitesRequired,
                         workflowCoverage: coverage.wire.workflowWriterPrerequisitesRequired,
                         planningOrderCoverage: coverage.wire.planningOrderWriterPrerequisitesRequired,
+                        taskCoverCoverage: coverage.wire.taskCoverProjectionRequired,
                         coveredLegacyWritesFenced: combinedLegacyPushDisabled })
                     : buildWorkspaceSyncV3InitiativeRepairPage({ core: input.core, workspaceId,
                         cursorKeyring: cursorKeyring, cursor: repairCursor,
@@ -399,6 +400,7 @@ export function registerWorkspaceSyncV3FeedRoutes(input) {
                         nestedCoverage: coverage.wire.nestedWriterPrerequisitesRequired,
                         workflowCoverage: coverage.wire.workflowWriterPrerequisitesRequired,
                         planningOrderCoverage: coverage.wire.planningOrderWriterPrerequisitesRequired,
+                        taskCoverCoverage: coverage.wire.taskCoverProjectionRequired,
                         coveredLegacyWritesFenced: combinedLegacyPushDisabled })
                     : buildWorkspaceSyncV3InitiativeRepairPage({ core: input.core, workspaceId,
                         cursorKeyring: cursorKeyring, pageSize: Number.isFinite(limit) ? limit : undefined });

package/dist/server/routes/syncV3LocalCaptureRoutes.js

@@ -96,7 +96,14 @@ function parseEnvelope(raw) {
     };
     if (operation.domain === 'task' && operation.mutationKind === 'metadata-update') {
         const saveSource = payload.saveSource;
-        assertExactKeys(payload, saveSource === undefined ? ['patch'] : ['patch', 'saveSource'], 'operation.payload');
+        const expectedDetailRevision = payload.expectedDetailRevision === undefined
+            ? undefined
+            : requireId(payload.expectedDetailRevision, 'operation.payload.expectedDetailRevision');
+        assertExactKeys(payload, [
+            'patch',
+            ...(saveSource === undefined ? [] : ['saveSource']),
+            ...(expectedDetailRevision === undefined ? [] : ['expectedDetailRevision']),
+        ], 'operation.payload');
         if (saveSource !== undefined && saveSource !== 'manual' && saveSource !== 'autosave') {
             throw new LocalCaptureRequestError('operation.payload.saveSource must be manual or autosave.');
         }
@@ -106,6 +113,7 @@ function parseEnvelope(raw) {
             mutationKind: 'metadata-update',
             patch: requireRecord(payload.patch, 'operation.payload.patch'),
             ...(saveSource ? { saveSource } : {}),
+            ...(expectedDetailRevision ? { expectedDetailRevision } : {}),
         };
     }
     if (operation.domain === 'task' && operation.mutationKind === 'create') {
@@ -170,11 +178,27 @@ function parseEnvelope(raw) {
         };
     }
     if (operation.domain === 'task' && operation.mutationKind === 'set-status') {
+        const expectedDetailRevision = payload.expectedDetailRevision === undefined
+            ? undefined
+            : requireId(payload.expectedDetailRevision, 'operation.payload.expectedDetailRevision');
+        assertExactKeys(payload, [
+            'status',
+            'assigneeIntent',
+            'canceledReason',
+            'metadataPatch',
+            ...(expectedDetailRevision === undefined ? [] : ['expectedDetailRevision']),
+        ], 'operation.payload');
         return {
             ...common,
             domain: 'task',
             mutationKind: 'set-status',
-            payload: validateDurableTaskStatusMutationPayload(payload),
+            payload: validateDurableTaskStatusMutationPayload({
+                status: payload.status,
+                assigneeIntent: payload.assigneeIntent,
+                canceledReason: payload.canceledReason,
+                metadataPatch: payload.metadataPatch,
+            }),
+            ...(expectedDetailRevision ? { expectedDetailRevision } : {}),
         };
     }
     if (operation.domain === 'task-comments' && operation.mutationKind === 'append') {
@@ -731,6 +755,7 @@ export function registerWorkspaceSyncV3LocalCaptureRoutes(input) {
                                                     taskId: envelope.entityId,
                                                     patch: envelope.patch,
                                                     saveSource: envelope.saveSource,
+                                                    expectedDetailRevision: envelope.expectedDetailRevision,
                                                     now: acceptedAt,
                                                     actorRef: 'user',
                                                     onPostCommitError: input.onPostCommitError,
@@ -786,6 +811,7 @@ export function registerWorkspaceSyncV3LocalCaptureRoutes(input) {
                                                                     identity,
                                                                     taskId: envelope.entityId,
                                                                     payload: envelope.payload,
+                                                                    expectedDetailRevision: envelope.expectedDetailRevision,
                                                                     now: acceptedAt,
                                                                     actorRef: 'user',
                                                                     onPostCommitError: input.onPostCommitError,

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

@@ -1,5 +1,6 @@
 import type { SyncAddRoute, SyncRouteAuthConfig, SyncRouteCore } from './syncRouteTypes.js';
 import type { LocalSyncCoordinatorRouteServices } from '../../sync/coordinator/localSyncCoordinatorRouteServices.js';
+export declare function revisionConflictDetails(error: unknown): Record<string, unknown> | undefined;
 export declare function isWorkspaceSyncV3LocalFeedApplyEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare function isWorkspaceSyncV3CombinedLocalFeedApplyEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare function registerWorkspaceSyncV3LocalFeedApplyRoutes(input: {

package/dist/server/routes/syncV3LocalFeedApplyRoutes.js

@@ -8,6 +8,7 @@ import { resolveCombinedFeedCapability, resolveRequestedCombinedFeedCoverage } f
 import { parseJsonBody } from './primitives.js';
 import { applyWorkspaceSyncV3TaskCommentAuditPage, readWorkspaceSyncV3TaskCommentAuditCursor, readWorkspaceSyncV3TaskCommentAuditState, } from '../../sync/v3/workspaceSyncV3TaskCommentAudit.js';
 import { createLocalSyncBrowserApplyPermitTransactionHooks, parseLocalSyncBrowserApplyPermitContext, } from '../../sync/coordinator/localSyncBrowserApplyPermitContext.js';
+import { WorkspaceSyncRevisionConflictError } from '../../sync/v3/syncDurabilityStore.js';
 const ROUTE_PATH = '/api/taskforce/sync/v3/local/feed';
 const TASK_COMMENT_AUDIT_PATH = '/api/taskforce/sync/v3/local/task-comment-audit';
 const MAX_BODY_BYTES = 8 * 1024 * 1024;
@@ -15,6 +16,29 @@ function writeJson(res, statusCode, body) {
     res.writeHead(statusCode, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
     res.end(JSON.stringify(body));
 }
+export function revisionConflictDetails(error) {
+    if (!(error instanceof WorkspaceSyncRevisionConflictError) || !error.details)
+        return undefined;
+    const details = error.details;
+    const coordinates = (value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const source = value;
+        const sequence = source.sequence ?? source.lastSequence;
+        return {
+            sequence: sequence == null ? null : String(sequence),
+            entityRevision: source.entityRevision == null ? null : String(source.entityRevision),
+            lifecycleRevision: source.lifecycleRevision == null ? null : String(source.lifecycleRevision),
+        };
+    };
+    return {
+        domain: String(details.domain || ''),
+        entityId: String(details.entityId || ''),
+        reason: String(details.reason || ''),
+        ...(coordinates(details.incoming) ? { incoming: coordinates(details.incoming) } : {}),
+        ...(coordinates(details.current) ? { current: coordinates(details.current) } : {}),
+    };
+}
 function workspaceFromUrl(req) {
     try {
         return String(new URL(req.url || ROUTE_PATH, 'http://localhost').searchParams.get('workspaceId') || '').trim();
@@ -481,12 +505,14 @@ export function registerWorkspaceSyncV3LocalFeedApplyRoutes(input) {
         catch (error) {
             const causeCode = String(error?.code || '').trim();
             const causeAssetId = String(error?.assetId || '').trim();
+            const causeDetails = revisionConflictDetails(error);
             writeJson(res, 409, {
                 success: false,
                 code: 'WORKSPACE_SYNC_V3_LOCAL_FEED_APPLY_REJECTED',
                 error: String(error?.message || error),
                 ...(causeCode ? { causeCode } : {}),
                 ...(causeAssetId ? { causeAssetId } : {}),
+                ...(causeDetails ? { causeDetails } : {}),
             });
         }
     });

package/dist/server/routes/syncV3OperationRoutes.js

@@ -157,9 +157,13 @@ export function parseWorkspaceSyncV3OperationEnvelope(body) {
     const payload = requireObject(operation.payload, 'operation.payload');
     if (operation.domain === 'task' && operation.mutationKind === 'metadata-update') {
         const saveSource = payload.saveSource;
+        const expectedDetailRevision = payload.expectedDetailRevision === undefined
+            ? undefined
+            : requireId(payload.expectedDetailRevision, 'operation.payload.expectedDetailRevision');
         assertExactKeys(payload, [
             'patch',
             ...(saveSource === undefined ? [] : ['saveSource']),
+            ...(expectedDetailRevision === undefined ? [] : ['expectedDetailRevision']),
             ...(payload.originActor === undefined ? [] : ['originActor']),
         ], 'operation.payload');
         if (saveSource !== undefined && saveSource !== 'manual' && saveSource !== 'autosave') {
@@ -173,6 +177,7 @@ export function parseWorkspaceSyncV3OperationEnvelope(body) {
                 payload: {
                     patch: requireObject(payload.patch, 'operation.payload.patch'),
                     ...(saveSource ? { saveSource } : {}),
+                    ...(expectedDetailRevision ? { expectedDetailRevision } : {}),
                     ...(originActor ? { originActor } : {}),
                 },
             } };
@@ -364,6 +369,7 @@ export function parseWorkspaceSyncV3OperationEnvelope(body) {
             ...baseKeys,
             ...(payload.workflowAssignment === undefined ? [] : ['workflowAssignment']),
             ...(payload.originActor === undefined ? [] : ['originActor']),
+            ...(payload.expectedDetailRevision === undefined ? [] : ['expectedDetailRevision']),
         ], 'operation.payload');
         const normalizedPayload = validateDurableTaskStatusMutationPayload({
             status: payload.status,
@@ -382,12 +388,16 @@ export function parseWorkspaceSyncV3OperationEnvelope(body) {
         const originActor = payload.originActor === undefined
             ? undefined
             : requireOriginActor(payload.originActor);
+        const expectedDetailRevision = payload.expectedDetailRevision === undefined
+            ? undefined
+            : requireId(payload.expectedDetailRevision, 'operation.payload.expectedDetailRevision');
         return { ...common, operation: {
                 domain: 'task', entityId, mutationKind: 'set-status', baseEntityRevision, baseLifecycleRevision,
                 payload: {
                     ...normalizedPayload,
                     ...(workflowAssignment ? { workflowAssignment } : {}),
                     ...(originActor ? { originActor } : {}),
+                    ...(expectedDetailRevision ? { expectedDetailRevision } : {}),
                 },
             } };
     }

package/dist/server/routes/tasks.js

@@ -470,9 +470,66 @@ export function registerTaskRoutes(deps) {
             res,
             route: '/api/taskforce/tasks',
             workspaceId,
-            load: () => core.listTasks(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))
             return;
@@ -617,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))
@@ -625,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;
@@ -658,10 +736,14 @@ export function registerTaskRoutes(deps) {
             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);
@@ -671,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: requestHumanActorRef(req),
-                            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));
@@ -711,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);
@@ -1291,7 +1381,9 @@ export function registerTaskRoutes(deps) {
             res,
             route: '/api/taskforce/archive',
             workspaceId,
-            load: () => core.listArchive(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

package/dist/server/routes/workspaces.js

@@ -17,9 +17,11 @@ import { parseJsonBody } from './primitives.js';
 import { resolveRequestAccess, createSessionTokenCookie, resolveSessionCookieAttributesForRequest, } from '../auth.js';
 import { isWorkspaceSwitchingEnabledForRuntime } from '../../shared/runtimeContract.js';
 import { getRouteTimingNow, logSlowBootstrapRoute, requestBootstrapTraceId, resolveErrorStatusCode, serializeJsonWithTiming, setServerTimingHeader } from './shared.js';
+import { WorkspaceDeletionAdmission } from '../workspaceDeletionAdmission.js';
 // === SECTION: Registration ===
 export function registerWorkspaceRoutes(deps) {
     const { addRoute, core, context, ensureAppAccess, auditAuthAction, getObjectStorageClient, ensureWithinDir, sanitizeStorageSegment, sanitizeTaskIdForPath, normalizeDocumentPathInput, } = deps;
+    const workspaceDeletionAdmission = new WorkspaceDeletionAdmission();
     // === SECTION: Storage cleanup helper ===
     const cleanupDeletedWorkspaceStorage = async (summary) => {
         const warnings = [];
@@ -231,12 +233,49 @@ export function registerWorkspaceRoutes(deps) {
             res.end(JSON.stringify({ success: false, error: 'workspaceId is required.', code: 'WORKSPACE_ID_REQUIRED' }));
             return;
         }
-        const resolvedAccess = core.resolveUserAccess(access.userId, targetWorkspaceId, 'member');
+        const writeAdmissionError = (decision) => {
+            res.setHeader('Retry-After', String(Math.max(1, Math.ceil(decision.retryAfterMs / 1_000))));
+            const inProgress = decision.code === 'WORKSPACE_DELETE_IN_PROGRESS';
+            res.writeHead(inProgress ? 409 : 429, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: inProgress
+                    ? 'Workspace deletion is already running for this workspace.'
+                    : 'Workspace deletion was attempted recently. Wait before retrying.',
+                code: decision.code,
+                retryAfterMs: decision.retryAfterMs,
+            }));
+        };
+        const existingAdmission = workspaceDeletionAdmission.checkExisting(targetWorkspaceId);
+        if (existingAdmission) {
+            writeAdmissionError(existingAdmission);
+            return;
+        }
+        let resolvedAccess;
+        try {
+            resolvedAccess = core.resolveUserAccess(access.userId, targetWorkspaceId, 'member');
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: String(error?.message || 'Unable to resolve workspace access'),
+                code: error?.code,
+            }));
+            return;
+        }
         if (!resolvedAccess || resolvedAccess.role !== 'owner' || resolvedAccess.disabled) {
             res.writeHead(403, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ success: false, error: 'Only workspace owners can delete this workspace.' }));
             return;
         }
+        const deletionAdmissionKey = targetWorkspaceId;
+        const admission = workspaceDeletionAdmission.acquire(deletionAdmissionKey);
+        if (!admission.allowed) {
+            writeAdmissionError(admission);
+            return;
+        }
         try {
             const deleted = core.deleteWorkspace({ workspaceId: targetWorkspaceId });
             const cleanupWarnings = await cleanupDeletedWorkspaceStorage(deleted);
@@ -277,6 +316,9 @@ export function registerWorkspaceRoutes(deps) {
                 code: error?.code
             }));
         }
+        finally {
+            workspaceDeletionAdmission.settle(deletionAdmissionKey);
+        }
     });
     // === SECTION: Session workspace switch ===
     // POST /api/taskforce/session/workspace - Switch active workspace in auth session

package/dist/server/workspaceDeletionAdmission.d.ts

@@ -0,0 +1,23 @@
+export declare const WORKSPACE_DELETE_RETRY_COOLDOWN_MS = 30000;
+export type WorkspaceDeletionAdmissionDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    code: 'WORKSPACE_DELETE_IN_PROGRESS' | 'WORKSPACE_DELETE_RETRY_COOLDOWN';
+    retryAfterMs: number;
+};
+/**
+ * Serializes destructive workspace cleanup inside one server process and
+ * throttles immediate retries after an attempt settles. The caller supplies
+ * time so the admission policy can be verified without timers.
+ */
+export declare class WorkspaceDeletionAdmission {
+    private readonly cooldownMs;
+    private readonly entries;
+    constructor(cooldownMs?: number);
+    checkExisting(key: string, now?: number): Exclude<WorkspaceDeletionAdmissionDecision, {
+        allowed: true;
+    }> | null;
+    acquire(key: string, now?: number): WorkspaceDeletionAdmissionDecision;
+    settle(key: string, now?: number): void;
+}