@taskforcehq/taskforce 0.3.328 → 0.3.330

package/dist/sync/workspaceRepair.js

@@ -6,6 +6,7 @@ import { resolveStorageKeyPathInsideRoot } from '../utils/pathSafety.js';
 import { compareWorkspaceMutationOrdering } from './workspaceSyncSurface.js';
 import { relativePathWithinRoot } from '../utils/pathContainment.js';
 import { listReferencedAiProfileAvatarAssetPaths, } from './aiProfileAvatarSyncPaths.js';
+import { WORKSPACE_CONTENT_MANIFEST_VERSION, createWorkspaceContentMetadataFingerprintV1, } from './workspaceContentManifest.js';
 function normalizeWorkspaceId(raw) {
     return String(raw || '').trim() || 'default';
 }
@@ -44,6 +45,14 @@ function collectFiles(dirPath, predicate) {
     visit(root);
     return output;
 }
+function isStorageRootAccessible(basePath) {
+    try {
+        return fs.statSync(basePath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function readFileFingerprint(absolutePath) {
     try {
         const stat = fs.statSync(absolutePath);
@@ -102,6 +111,68 @@ function getPrimaryTaskId(store, assetId, workspaceId) {
     const links = store.listLinksForAsset(assetId, workspaceId, { includeDeleted: false });
     return links[0]?.taskId || null;
 }
+function buildContentPullObligationInputForAsset(input) {
+    const links = input.store.listLinksForAsset(input.entry.assetId, input.workspaceId, { includeDeleted: false });
+    const primaryLink = links[0] || null;
+    // Mirrors resolveSyncLinkTarget (src/sync/contentSyncState.ts): a task link has no
+    // explicit targetType on the row (it's implied), so it must default to 'task' here
+    // rather than null — otherwise this fingerprint diverges from the one a real content
+    // manifest read (workspacePullFeed.ts) computes for the same task-linked asset, and
+    // the 'exact-version' obligation-resolution path can never match it.
+    const primaryLinkTargetId = String(primaryLink?.targetId || primaryLink?.taskId || '').trim();
+    const linkTargetType = primaryLinkTargetId
+        ? (primaryLink.targetType === 'initiative' || primaryLink.targetType === 'workstream' ? primaryLink.targetType : 'task')
+        : null;
+    const linkTargetId = linkTargetType ? primaryLinkTargetId : null;
+    const taskId = linkTargetType === 'task' ? linkTargetId : null;
+    const metadataFingerprint = input.kind === 'document'
+        ? createWorkspaceContentMetadataFingerprintV1({
+            kind: 'document',
+            metadata: {
+                assetId: input.entry.assetId,
+                documentId: input.entry.documentId,
+                referenceNumber: input.entry.referenceNumber,
+                version: input.entry.version,
+                taskId,
+                linkTargetType,
+                linkTargetId,
+                logicalName: input.entry.logicalName,
+                caption: null,
+                originalFilename: input.entry.originalFilename,
+                linkRole: primaryLink?.role === 'reference' ? 'reference' : 'attachment',
+            },
+        })
+        : createWorkspaceContentMetadataFingerprintV1({
+            kind: 'asset',
+            metadata: {
+                assetId: input.entry.assetId,
+                assetKind: input.entry.kind === 'image' ? 'image' : 'file',
+                mimeType: input.entry.mimeType,
+                referenceNumber: input.entry.referenceNumber,
+                taskId,
+                linkTargetType,
+                linkTargetId,
+                logicalName: input.entry.logicalName,
+                caption: null,
+                originalFilename: input.entry.originalFilename,
+                linkRole: primaryLink?.role || 'attachment',
+            },
+        });
+    const manifest = {
+        manifestVersion: WORKSPACE_CONTENT_MANIFEST_VERSION,
+        kind: input.kind,
+        path: input.path,
+        sha256: String(input.entry.contentSha256 || ''),
+        sizeBytes: Number(input.entry.sizeBytes || 0),
+        updatedAt: input.entry.updatedAt,
+        metadataFingerprint,
+        existsLocally: false,
+    };
+    return {
+        manifest,
+        sourceWatermark: input.entry.updatedAt,
+    };
+}
 function decodePathSegment(raw) {
     try {
         return decodeURIComponent(raw);
@@ -145,6 +216,7 @@ function buildManifestEntriesFromMetadata(tenantId, workspaceId, store, basePath
     const assetDeletes = [];
     const protectedDocumentPaths = new Set();
     const protectedAssetPaths = new Set();
+    const storageRootAccessible = isStorageRootAccessible(basePath);
     const metadataEntries = store.listAllByWorkspace(workspaceId, { includeDeleted: true });
     for (const entry of metadataEntries) {
         const contentKind = entry.kind === 'document' ? 'document' : 'asset';
@@ -192,6 +264,7 @@ function buildManifestEntriesFromMetadata(tenantId, workspaceId, store, basePath
             ? resolveStorageKeyPathInsideRoot(basePath, published.physicalKey)
             : null;
         let existsLocally = false;
+        let contentCheckReliable = true;
         if (!supportsPublishedContent) {
             existsLocally = true;
         }
@@ -200,13 +273,23 @@ function buildManifestEntriesFromMetadata(tenantId, workspaceId, store, basePath
                 existsLocally = true;
             }
             else if (physicalPath) {
-                try {
-                    const stat = fs.statSync(physicalPath);
-                    existsLocally = stat.isFile()
-                        && (published.source !== 'versioned' || stat.size === published.sizeBytes);
-                }
-                catch {
+                if (!storageRootAccessible) {
+                    // The storage root itself couldn't be verified (e.g. an unmounted volume or
+                    // transient I/O failure) — every local file would look "missing" in that state,
+                    // so don't let a whole-root outage masquerade as N individual deletions.
                     existsLocally = false;
+                    contentCheckReliable = false;
+                }
+                else {
+                    try {
+                        const stat = fs.statSync(physicalPath);
+                        existsLocally = stat.isFile()
+                            && (published.source !== 'versioned' || stat.size === published.sizeBytes);
+                    }
+                    catch (error) {
+                        existsLocally = false;
+                        contentCheckReliable = error?.code === 'ENOENT';
+                    }
                 }
             }
         }
@@ -231,6 +314,7 @@ function buildManifestEntriesFromMetadata(tenantId, workspaceId, store, basePath
                 sha256: contentSha256,
                 sizeBytes,
                 existsLocally,
+                contentCheckReliable,
                 source: 'metadata',
                 publicationState,
                 publicationError,
@@ -249,6 +333,7 @@ function buildManifestEntriesFromMetadata(tenantId, workspaceId, store, basePath
             sha256: contentSha256,
             sizeBytes,
             existsLocally,
+            contentCheckReliable,
             source: 'metadata',
             publicationState,
             publicationError,
@@ -307,6 +392,7 @@ export function buildWorkspaceRepairManifest(input) {
                 sha256: fingerprint.sha256,
                 sizeBytes: fingerprint.sizeBytes,
                 existsLocally: true,
+                contentCheckReliable: true,
                 source: 'filesystem',
                 publicationState: 'legacy',
                 publicationError: null,
@@ -337,6 +423,7 @@ export function buildWorkspaceRepairManifest(input) {
             sha256: fingerprint.sha256,
             sizeBytes: fingerprint.sizeBytes,
             existsLocally: true,
+            contentCheckReliable: true,
             source: 'filesystem',
             publicationState: 'legacy',
             publicationError: null,
@@ -466,6 +553,19 @@ export function scanWorkspaceRepair(input) {
             continue;
         }
         if (!document.existsLocally) {
+            if (!document.contentCheckReliable) {
+                issues.push({
+                    code: 'document_content_unverified',
+                    entityKind: 'document',
+                    path: document.path,
+                    assetId: document.assetId,
+                    taskId: document.taskId,
+                    repairable: false,
+                    recommendedAction: 'retry-pull',
+                    detail: 'Local document file could not be confirmed missing — the storage root was unreachable or the check was inconclusive. Skipped to avoid converting unavailable content into an authoritative deletion; queued for durable retry instead.'
+                });
+                continue;
+            }
             issues.push({
                 code: 'missing_document_file',
                 entityKind: 'document',
@@ -564,6 +664,19 @@ export function scanWorkspaceRepair(input) {
         if (!asset.existsLocally) {
             if (protectedAiAvatarAssetPaths.has(asset.path))
                 continue;
+            if (!asset.contentCheckReliable) {
+                issues.push({
+                    code: 'asset_content_unverified',
+                    entityKind: 'asset',
+                    path: asset.path,
+                    assetId: asset.assetId,
+                    taskId: asset.taskId,
+                    repairable: false,
+                    recommendedAction: 'retry-pull',
+                    detail: 'Local asset file could not be confirmed missing — the storage root was unreachable or the check was inconclusive. Skipped to avoid converting unavailable content into an authoritative deletion; queued for durable retry instead.'
+                });
+                continue;
+            }
             issues.push({
                 code: 'missing_asset_file',
                 entityKind: 'asset',
@@ -721,6 +834,7 @@ export function applyWorkspaceRepair(input) {
     const actionsApplied = [];
     const workspaceId = normalizeWorkspaceId(input.workspaceId);
     const activeTaskIds = new Set((input.tasks || []).map((task) => String(task.id || '').trim()).filter(Boolean));
+    const nowIso = () => (input.now ? input.now() : new Date().toISOString());
     const deletedMetadataByPath = new Map();
     if (input.workspaceAssetStore) {
         for (const entry of input.workspaceAssetStore.listAllByWorkspace(workspaceId, { includeDeleted: true })) {
@@ -730,6 +844,69 @@ export function applyWorkspaceRepair(input) {
         }
     }
     for (const issue of scan.issues) {
+        if (issue.code === 'document_content_unverified' || issue.code === 'asset_content_unverified') {
+            if (!input.contentPullObligationStore || !input.workspaceAssetStore || !issue.assetId || !issue.path) {
+                actionsApplied.push({
+                    code: issue.code,
+                    path: issue.path,
+                    assetId: issue.assetId,
+                    taskId: issue.taskId,
+                    action: issue.recommendedAction,
+                    status: 'skipped',
+                    detail: 'No durable content-pull obligation store is available in this runtime; content-availability uncertainty was reported but not queued for retry.'
+                });
+                continue;
+            }
+            try {
+                const assetEntry = input.workspaceAssetStore.get(issue.assetId, workspaceId);
+                if (!assetEntry) {
+                    actionsApplied.push({
+                        code: issue.code,
+                        path: issue.path,
+                        assetId: issue.assetId,
+                        taskId: issue.taskId,
+                        action: issue.recommendedAction,
+                        status: 'skipped',
+                        detail: 'Canonical metadata for this asset was no longer present; skipped queuing a recovery obligation.'
+                    });
+                    continue;
+                }
+                const obligationInput = buildContentPullObligationInputForAsset({
+                    kind: issue.code === 'document_content_unverified' ? 'document' : 'asset',
+                    path: issue.path,
+                    entry: assetEntry,
+                    store: input.workspaceAssetStore,
+                    workspaceId,
+                });
+                input.contentPullObligationStore.upsertMany({
+                    tenantId: input.tenantId,
+                    workspaceId,
+                    obligations: [obligationInput],
+                    now: nowIso(),
+                });
+                actionsApplied.push({
+                    code: issue.code,
+                    path: issue.path,
+                    assetId: issue.assetId,
+                    taskId: issue.taskId,
+                    action: issue.recommendedAction,
+                    status: 'applied',
+                    detail: 'Queued a durable content-pull recovery obligation instead of treating unavailable content as deleted.'
+                });
+            }
+            catch (error) {
+                actionsApplied.push({
+                    code: issue.code,
+                    path: issue.path,
+                    assetId: issue.assetId,
+                    taskId: issue.taskId,
+                    action: issue.recommendedAction,
+                    status: 'failed',
+                    detail: String(error?.message || error || 'Failed to queue a recovery obligation.')
+                });
+            }
+            continue;
+        }
         if (!issue.repairable) {
             actionsApplied.push({
                 code: issue.code,
@@ -791,6 +968,17 @@ export function applyWorkspaceRepair(input) {
                 continue;
             }
             if ((issue.code === 'missing_document_file' || issue.code === 'missing_asset_file') && issue.assetId) {
+                if (input.repairMissingContentFiles !== true) {
+                    actionsApplied.push({
+                        code: issue.code,
+                        path: issue.path,
+                        assetId: issue.assetId,
+                        action: issue.recommendedAction,
+                        status: 'skipped',
+                        detail: 'Missing content file repair requires explicit admin confirmation, since a single failed existence check can also mean the content is temporarily unavailable rather than deleted.'
+                    });
+                    continue;
+                }
                 const updated = input.workspaceAssetStore.markDeleted(issue.assetId, workspaceId);
                 actionsApplied.push({
                     code: issue.code,
@@ -886,6 +1074,34 @@ export function applyWorkspaceRepair(input) {
             });
         }
     }
+    if (input.contentPullObligationStore) {
+        const resolutionClaims = [
+            ...scan.snapshot.documents
+                .filter((entry) => entry.existsLocally && entry.assetId)
+                .map((entry) => ({
+                kind: 'document',
+                path: entry.path,
+                sourceWatermark: entry.updatedAt,
+                resolution: 'at-or-before-watermark',
+            })),
+            ...scan.snapshot.assets
+                .filter((entry) => entry.existsLocally && entry.assetId)
+                .map((entry) => ({
+                kind: 'asset',
+                path: entry.path,
+                sourceWatermark: entry.updatedAt,
+                resolution: 'at-or-before-watermark',
+            })),
+        ];
+        if (resolutionClaims.length > 0) {
+            input.contentPullObligationStore.resolveMany({
+                tenantId: input.tenantId,
+                workspaceId,
+                claims: resolutionClaims,
+                now: nowIso(),
+            });
+        }
+    }
     const refreshed = scanWorkspaceRepair(input);
     return {
         ...refreshed,

package/dist/sync/workspaceSyncModel.d.ts

@@ -229,6 +229,9 @@ export interface WorkspaceSyncInitiativeSnapshot {
     order?: number | null;
     attachments?: Array<string | AttachmentItem>;
     isArchived?: boolean;
+    icon?: PlanningIdentityIcon | null;
+    color?: PlanningIdentityColor | null;
+    identityUpdatedAt?: string | null;
     durableRevision?: WorkspaceSyncDurablePlanningRevision<'initiative'>;
 }
 export interface WorkspaceSyncWorkstreamSnapshot {
@@ -245,6 +248,9 @@ export interface WorkspaceSyncWorkstreamSnapshot {
     order?: number | null;
     attachments?: Array<string | AttachmentItem>;
     isArchived?: boolean;
+    icon?: PlanningIdentityIcon | null;
+    color?: PlanningIdentityColor | null;
+    identityUpdatedAt?: string | null;
     durableRevision?: WorkspaceSyncDurablePlanningRevision<'workstream'>;
 }
 export interface WorkspaceSyncPlanningIdentitySnapshot {
@@ -425,6 +431,7 @@ export interface WorkspaceSyncPayload {
     currentInitiativeWatermarks: Map<string, string>;
     currentWorkstreamIds: Set<string>;
     currentWorkstreamWatermarks: Map<string, string>;
+    currentPlanningIdentityWatermarks?: Map<string, string>;
     currentAiProfileIds: Set<string>;
     currentAiProfileWatermarks: Map<string, string>;
     currentAiProfileChangeKeys?: Map<string, string>;
@@ -472,6 +479,7 @@ export interface WorkspaceSyncDeltaDiagnostics {
         taskRelationships?: WorkspaceSyncDomainDeltaDiagnostics;
         initiatives: WorkspaceSyncDomainDeltaDiagnostics;
         workstreams: WorkspaceSyncDomainDeltaDiagnostics;
+        planningIdentities?: WorkspaceSyncDomainDeltaDiagnostics;
         aiProfiles: WorkspaceSyncDomainDeltaDiagnostics;
         documents: WorkspaceSyncDomainDeltaDiagnostics;
         assets: WorkspaceSyncDomainDeltaDiagnostics;
@@ -537,6 +545,18 @@ export declare function buildWorkspaceSyncPayloadModel(input: {
     assets?: WorkspaceSyncAssetSnapshot[];
     currentDocumentPaths?: Iterable<string>;
     currentAssetPaths?: Iterable<string>;
+    /**
+     * Positive completeness signal for the current-workspace document/asset
+     * snapshot used to compute deleteDocumentPaths/deleteAssetPaths. Explicit
+     * `false` means the snapshot is known failed, partial, stale, for the wrong
+     * workspace, or not yet hydrated — the delete-diff for that domain is
+     * suppressed entirely rather than trusted. Omitted/undefined defaults to
+     * `true` for callers (tests, other pure-function consumers) that don't model
+     * hydration state; the real browser sync orchestrator always passes the
+     * verified value.
+     */
+    documentsSnapshotComplete?: boolean;
+    assetsSnapshotComplete?: boolean;
     documentReviewSessions?: WorkspaceSyncDocumentReviewSessionSnapshot[];
     documentReviewComments?: WorkspaceSyncDocumentReviewCommentSnapshot[];
     annotatedAttachmentSessions?: WorkspaceSyncAnnotatedAttachmentSessionSnapshot[];
@@ -549,6 +569,7 @@ export declare function buildWorkspaceSyncPayloadModel(input: {
     lastPushedInitiativeWatermarks?: Map<string, string>;
     lastPushedWorkstreamIds?: Set<string>;
     lastPushedWorkstreamWatermarks?: Map<string, string>;
+    lastPushedPlanningIdentityWatermarks?: Map<string, string>;
     lastPushedAiProfileIds?: Set<string>;
     lastPushedAiProfileWatermarks?: Map<string, string>;
     lastPushedDocumentPaths?: Set<string>;

package/dist/sync/workspaceSyncModel.js

@@ -223,6 +223,8 @@ export function buildWorkspaceSyncPayloadModel(input) {
             return true;
         return previousWorkstreamWatermarks.get(change.workstream.id) !== change.workstream.updatedAt;
     });
+    const previousPlanningIdentityWatermarks = input.lastPushedPlanningIdentityWatermarks;
+    const currentPlanningIdentityWatermarks = new Map();
     const planningIdentityUpsertChanges = [
         ...(Array.isArray(input.initiatives) ? input.initiatives : []).map((initiative) => ({
             entityType: 'initiative',
@@ -240,7 +242,13 @@ export function buildWorkspaceSyncPayloadModel(input) {
         })),
     ]
         .filter((identity) => identity.entityId.length > 0 && Number.isFinite(Date.parse(identity.updatedAt)))
-        .map((identity) => ({ op: 'planning-identity-upsert', identity }));
+        .map((identity) => {
+        const identityKey = `${identity.entityType}:${identity.entityId}`;
+        currentPlanningIdentityWatermarks.set(identityKey, identity.updatedAt);
+        return { op: 'planning-identity-upsert', identity, identityKey };
+    })
+        .filter((change) => previousPlanningIdentityWatermarks?.get(change.identityKey) !== change.identity.updatedAt)
+        .map(({ identityKey: _identityKey, ...change }) => change);
     const currentAiProfileIds = new Set((Array.isArray(input.aiProfiles) ? input.aiProfiles : [])
         .map((profile) => String(profile?.id || '').trim())
         .filter((profileId) => profileId.length > 0));
@@ -312,9 +320,18 @@ export function buildWorkspaceSyncPayloadModel(input) {
     });
     const currentDocumentPaths = normalizeWorkspaceSyncPathSet(input.currentDocumentPaths, (Array.isArray(input.documents) ? input.documents : [])
         .map((doc) => String(doc?.path || '').trim()));
-    const deleteDocumentPaths = new Set(Array.from(input.lastPushedDocumentPaths || new Set())
-        .map((docPath) => String(docPath || '').trim())
-        .filter((docPath) => docPath.length > 0 && !currentDocumentPaths.has(docPath)));
+    // A raw set-difference against the previous push is only trustworthy when the
+    // current snapshot is a verified-complete, current-workspace read. A failed,
+    // partial, stale, or not-yet-hydrated snapshot must never be interpreted as
+    // deletion intent — so documentsSnapshotComplete === false suppresses the
+    // entire delete-diff for this cycle rather than trusting a plausible-looking
+    // but potentially wrong difference.
+    const documentsSnapshotComplete = input.documentsSnapshotComplete !== false;
+    const deleteDocumentPaths = documentsSnapshotComplete
+        ? new Set(Array.from(input.lastPushedDocumentPaths || new Set())
+            .map((docPath) => String(docPath || '').trim())
+            .filter((docPath) => docPath.length > 0 && !currentDocumentPaths.has(docPath)))
+        : new Set();
     const currentDocumentWatermarks = new Map((Array.isArray(input.documents) ? input.documents : [])
         .map((doc) => [String(doc?.path || '').trim(), String(doc?.updatedAt || '').trim()])
         .filter(([docPath]) => docPath.length > 0));
@@ -349,9 +366,14 @@ export function buildWorkspaceSyncPayloadModel(input) {
     });
     const currentAssetPaths = normalizeWorkspaceSyncPathSet(input.currentAssetPaths, (Array.isArray(input.assets) ? input.assets : [])
         .map((asset) => String(asset?.path || '').trim()));
-    const deleteAssetPaths = new Set(Array.from(input.lastPushedAssetPaths || new Set())
-        .map((assetPath) => String(assetPath || '').trim())
-        .filter((assetPath) => assetPath.length > 0 && !currentAssetPaths.has(assetPath)));
+    // See documentsSnapshotComplete above — the same admission boundary applies
+    // to assets.
+    const assetsSnapshotComplete = input.assetsSnapshotComplete !== false;
+    const deleteAssetPaths = assetsSnapshotComplete
+        ? new Set(Array.from(input.lastPushedAssetPaths || new Set())
+            .map((assetPath) => String(assetPath || '').trim())
+            .filter((assetPath) => assetPath.length > 0 && !currentAssetPaths.has(assetPath)))
+        : new Set();
     const currentAssetWatermarks = new Map((Array.isArray(input.assets) ? input.assets : [])
         .map((asset) => [String(asset?.path || '').trim(), String(asset?.updatedAt || '').trim()])
         .filter(([assetPath]) => assetPath.length > 0));
@@ -958,6 +980,7 @@ export function buildWorkspaceSyncPayloadModel(input) {
         currentInitiativeWatermarks,
         currentWorkstreamIds,
         currentWorkstreamWatermarks,
+        currentPlanningIdentityWatermarks,
         currentAiProfileIds,
         currentAiProfileWatermarks,
         currentAiProfileChangeKeys,
@@ -1012,6 +1035,11 @@ export function buildWorkspaceSyncPayloadModel(input) {
                     baselineCount: previousWorkstreamWatermarks?.size || 0,
                     upsertCount: workstreamUpsertChanges.length
                 }),
+                planningIdentities: resolveDomainDeltaDiagnostics({
+                    currentCount: currentPlanningIdentityWatermarks.size,
+                    baselineCount: previousPlanningIdentityWatermarks?.size || 0,
+                    upsertCount: planningIdentityUpsertChanges.length
+                }),
                 aiProfiles: resolveDomainDeltaDiagnostics({
                     currentCount: currentAiProfileIds.size,
                     baselineCount: previousAiProfileWatermarks?.size || 0,

package/dist/sync/workspaceSyncState.d.ts

@@ -11,6 +11,7 @@ export interface WorkspaceSyncPushBaselineSnapshot {
     taskRelationshipChangeKeys?: Array<[string, string]>;
     initiativeWatermarks: Array<[string, string]>;
     workstreamWatermarks: Array<[string, string]>;
+    planningIdentityWatermarks?: Array<[string, string]>;
     aiProfileWatermarks: Array<[string, string]>;
     aiProfileChangeKeys?: Array<[string, string]>;
     taskforceAgentWatermarks?: Array<[string, string]>;

package/dist/sync/workspaceSyncV2SnapshotBuilder.d.ts

@@ -19,6 +19,9 @@ export interface WorkspaceSyncV2SnapshotInput {
     assets?: readonly WorkspaceSyncAssetSnapshot[];
     currentDocumentPaths?: ReadonlySet<string>;
     currentAssetPaths?: ReadonlySet<string>;
+    /** See WorkspaceSyncPayloadModel's documentsSnapshotComplete/assetsSnapshotComplete. */
+    documentsSnapshotComplete?: boolean;
+    assetsSnapshotComplete?: boolean;
     documentReviewSessions?: readonly WorkspaceSyncDocumentReviewSessionSnapshot[];
     documentReviewComments?: readonly WorkspaceSyncDocumentReviewCommentSnapshot[];
     annotatedAttachmentSessions?: readonly WorkspaceSyncAnnotatedAttachmentSessionSnapshot[];
@@ -45,6 +48,8 @@ export interface WorkspaceSyncV2FrozenSnapshot {
     readonly assets: readonly WorkspaceSyncAssetSnapshot[];
     readonly currentDocumentPaths: ReadonlySet<string>;
     readonly currentAssetPaths: ReadonlySet<string>;
+    readonly documentsSnapshotComplete: boolean;
+    readonly assetsSnapshotComplete: boolean;
     readonly documentReviewSessions: readonly WorkspaceSyncDocumentReviewSessionSnapshot[];
     readonly documentReviewComments: readonly WorkspaceSyncDocumentReviewCommentSnapshot[];
     readonly annotatedAttachmentSessions: readonly WorkspaceSyncAnnotatedAttachmentSessionSnapshot[];
@@ -64,6 +69,7 @@ export interface WorkspaceSyncV2PushBaseline {
     readonly lastPushedInitiativeWatermarks: ReadonlyMap<string, string>;
     readonly lastPushedWorkstreamIds: ReadonlySet<string>;
     readonly lastPushedWorkstreamWatermarks: ReadonlyMap<string, string>;
+    readonly lastPushedPlanningIdentityWatermarks?: ReadonlyMap<string, string>;
     readonly lastPushedAiProfileIds: ReadonlySet<string>;
     readonly lastPushedAiProfileWatermarks: ReadonlyMap<string, string>;
     readonly lastPushedAiProfileChangeKeys: ReadonlyMap<string, string>;

package/dist/sync/workspaceSyncV2SnapshotBuilder.js

@@ -62,6 +62,8 @@ export function createWorkspaceSyncV2FrozenSnapshot(input) {
         assets,
         currentDocumentPaths: stringSet(input.currentDocumentPaths, documents.map((entry) => entry.path)),
         currentAssetPaths: stringSet(input.currentAssetPaths, assets.map((entry) => entry.path)),
+        documentsSnapshotComplete: input.documentsSnapshotComplete !== false,
+        assetsSnapshotComplete: input.assetsSnapshotComplete !== false,
         documentReviewSessions: frozenArray(input.documentReviewSessions),
         documentReviewComments: frozenArray(input.documentReviewComments),
         annotatedAttachmentSessions: frozenArray(input.annotatedAttachmentSessions),
@@ -119,6 +121,7 @@ export function buildWorkspaceSyncV2Candidate(input) {
         lastPushedInitiativeWatermarks: mutableMap(baseline.lastPushedInitiativeWatermarks),
         lastPushedWorkstreamIds: mutableSet(baseline.lastPushedWorkstreamIds),
         lastPushedWorkstreamWatermarks: mutableMap(baseline.lastPushedWorkstreamWatermarks),
+        lastPushedPlanningIdentityWatermarks: mutableMap(baseline.lastPushedPlanningIdentityWatermarks || new Map()),
         aiProfiles: Array.from(snapshot.aiProfiles),
         lastPushedAiProfileIds: forceAllAiProfiles ? new Set() : mutableSet(baseline.lastPushedAiProfileIds),
         lastPushedAiProfileWatermarks: forceAllAiProfiles ? new Map() : mutableMap(baseline.lastPushedAiProfileWatermarks),
@@ -127,6 +130,8 @@ export function buildWorkspaceSyncV2Candidate(input) {
         assets: Array.from(snapshot.assets),
         currentDocumentPaths: snapshot.currentDocumentPaths,
         currentAssetPaths: snapshot.currentAssetPaths,
+        documentsSnapshotComplete: snapshot.documentsSnapshotComplete,
+        assetsSnapshotComplete: snapshot.assetsSnapshotComplete,
         documentReviewSessions: Array.from(snapshot.documentReviewSessions),
         documentReviewComments: Array.from(snapshot.documentReviewComments),
         annotatedAttachmentSessions: Array.from(snapshot.annotatedAttachmentSessions),

package/dist/types.d.ts

@@ -8,6 +8,7 @@ export type { TaskActor } from './shared/taskActor.js';
 import type { TaskforceTheme } from './utils/theme';
 import type { TaskActor } from './shared/taskActor.js';
 import type { PlanningIdentityColor, PlanningIdentityIcon } from './shared/planningIdentity.js';
+import type { ResolvedFeatureAccessMap } from './runtime/appGates.js';
 export interface Comment {
     id: string;
     author: 'user' | 'ai' | string;
@@ -68,6 +69,17 @@ export interface AuditActivityItem {
     event: TaskEvent;
 }
 export type TaskActivityItem = CommentActivityItem | AuditActivityItem;
+export type TaskActivitySummaryItem = {
+    id: string;
+    type: 'comment';
+    timestamp: string;
+    comment: Pick<Comment, 'text' | 'author' | 'actor'>;
+} | {
+    id: string;
+    type: 'event';
+    timestamp: string;
+    event: Pick<TaskEvent, 'action' | 'details' | 'actor' | 'actorType' | 'actorProfile'>;
+};
 export interface EntityAuditActivityItem {
     id: string;
     type: 'event';
@@ -244,6 +256,7 @@ export interface TaskItem {
     taskEvents?: TaskEvent[];
     attachments?: Array<string | AttachmentItem>;
     cardCoverAssetId?: string | null;
+    cardCoverAttachment?: AttachmentItem | null;
     /** @deprecated Use status='cancelled'. Safe to remove after v0.4.x migration gate. */
     cancelled?: boolean;
     /** @deprecated Use status='done'. Safe to remove after v0.4.x migration gate. */
@@ -267,7 +280,27 @@ export interface TaskItem {
     workstreamOrder?: number | null;
     workstreamId?: string | null;
     checklistItems?: ChecklistItem[];
+    /** True when this object came from a collection read and omits the full task graph. */
+    isSummary?: boolean;
+    commentCount?: number;
+    checklistCount?: number;
+    completedChecklistCount?: number;
+    attachmentCount?: number;
+    relationshipCount?: number;
+    /** Compact newest comment or audit event carried by lightweight collection reads. */
+    latestActivity?: TaskActivitySummaryItem | null;
+    detailRevision?: string;
 }
+export type TaskSummary = Omit<TaskItem, 'description' | 'comments' | 'activity' | 'taskEvents' | 'attachments' | 'checklistItems'> & {
+    isSummary: true;
+    commentCount: number;
+    checklistCount: number;
+    completedChecklistCount: number;
+    attachmentCount: number;
+    relationshipCount: number;
+    latestActivity: TaskActivitySummaryItem | null;
+    detailRevision: string;
+};
 export interface CategoryConfig {
     value: string;
     label: string;
@@ -310,6 +343,8 @@ export interface TaskforceConfig {
     cloudMcpBaseUrl?: string;
     /** Optional absolute/relative base URL for Taskforce websocket (defaults to apiBaseUrl or current origin) */
     wsBaseUrl?: string;
+    /** Server-resolved feature availability for the active deployment environment. */
+    appGates?: ResolvedFeatureAccessMap;
     /** Button position on screen */
     position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
     /** Vertical offset from edge (useful for stacking with other widgets) */
@@ -324,16 +359,27 @@ export interface TaskforceConfig {
     checklistDropdownEnabled?: boolean;
     /** Show status text labels in task card status controls */
     showTaskCardStatusLabel?: boolean;
+    /** Show task descriptions on task cards when the runtime provides them */
+    showTaskCardDescription?: boolean;
+    /** Show compact image and document attachment rows on task cards */
+    showTaskCardAttachments?: boolean;
+    /** Show checklist completion progress on task cards */
+    showTaskCardChecklistProgress?: boolean;
+    /** Show the latest activity summary on task cards */
+    showTaskCardLatestActivity?: boolean;
+    /** Tint the latest activity background with the actor's signature color */
+    tintTaskCardActivityBackground?: boolean;
 }
 export interface TaskforcePluginOptions {
     /** Path to store JSON files (relative to project root) */
     outputPath?: string;
 }
-export declare const DEFAULT_CONFIG: Required<Omit<TaskforceConfig, 'apiEndpoint' | 'apiBaseUrl' | 'cloudAuthBaseUrl' | 'cloudMcpBaseUrl' | 'wsBaseUrl' | 'taxonomies'>> & {
+export declare const DEFAULT_CONFIG: Required<Omit<TaskforceConfig, 'apiEndpoint' | 'apiBaseUrl' | 'cloudAuthBaseUrl' | 'cloudMcpBaseUrl' | 'wsBaseUrl' | 'appGates' | 'taxonomies'>> & {
     apiEndpoint: string;
     apiBaseUrl?: string;
     cloudAuthBaseUrl?: string;
     cloudMcpBaseUrl?: string;
     wsBaseUrl?: string;
+    appGates?: ResolvedFeatureAccessMap;
     taxonomies: TaxonomyDefinition[];
 };

package/dist/types.js

@@ -14,6 +14,7 @@ export const DEFAULT_CONFIG = {
     cloudAuthBaseUrl: undefined,
     cloudMcpBaseUrl: undefined,
     wsBaseUrl: undefined,
+    appGates: undefined,
     position: 'bottom-right',
     offsetY: 70,
     theme: 'dawn',
@@ -21,4 +22,9 @@ export const DEFAULT_CONFIG = {
     manualComplexityEnabled: false,
     checklistDropdownEnabled: true,
     showTaskCardStatusLabel: false,
+    showTaskCardDescription: true,
+    showTaskCardAttachments: true,
+    showTaskCardChecklistProgress: true,
+    showTaskCardLatestActivity: true,
+    tintTaskCardActivityBackground: false,
 };