@taskforcehq/taskforce 0.3.327 → 0.3.328

package/dist/sync/coordinator/localSyncExecutionPermitStore.js

@@ -21,6 +21,8 @@ const NON_APPLYING_OPERATION_CLASSES = new Set([
 const MAX_DRAIN_INSPECTION_LIMIT = 500;
 export const LOCAL_SYNC_PERMIT_RETENTION_MIN_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 export const LOCAL_SYNC_PERMIT_RETENTION_SOFT_LIMIT = 1_000;
+export const LOCAL_SYNC_PERMIT_RETENTION_HARD_LIMIT = 10_000;
+export const LOCAL_SYNC_OBLIGATION_RETENTION_HARD_LIMIT = 2_000;
 export const LOCAL_SYNC_PERMIT_RETENTION_DELETE_BATCH = 250;
 export const LOCAL_SYNC_PERMIT_RETENTION_SWEEP_LIMIT = 5_000;
 const LOCAL_SYNC_PERMIT_RETENTION_CHECK_INTERVAL_MS = 60 * 60 * 1000;
@@ -166,11 +168,29 @@ export class LocalSyncExecutionPermitStore {
             FROM local_sync_recovery_obligations
             WHERE workspace_id = ? AND resolved_at IS NULL
         `).get(workspaceId);
+        const terminalHistory = this.db.prepare(`
+            SELECT COUNT(*) AS count, MIN(completed_at) AS oldest_at
+            FROM local_sync_execution_permits
+            WHERE workspace_id = ?
+              AND state IN ('released', 'abandoned-clean', 'abandoned-reconcile-required')
+              AND completed_at IS NOT NULL
+        `).get(workspaceId);
+        const resolvedHistory = this.db.prepare(`
+            SELECT COUNT(*) AS count, MIN(resolved_at) AS oldest_at
+            FROM local_sync_recovery_obligations
+            WHERE workspace_id = ? AND resolved_at IS NOT NULL
+        `).get(workspaceId);
         return {
             active,
             byState,
             recoveryObligations: Number(obligation?.count || 0),
             localCommitInvariantViolation: this.invariantBlockedWorkspaces.has(workspaceId),
+            history: {
+                terminalPermits: Number(terminalHistory?.count || 0),
+                oldestTerminalPermitAt: terminalHistory?.oldest_at || null,
+                resolvedRecoveryObligations: Number(resolvedHistory?.count || 0),
+                oldestResolvedRecoveryObligationAt: resolvedHistory?.oldest_at || null,
+            },
         };
     }
     inspectGenerationDrain(input) {
@@ -417,6 +437,42 @@ export class LocalSyncExecutionPermitStore {
             });
         })();
     }
+    renewAcceptedApplyCompletion(input) {
+        return this.db.transaction(() => {
+            const current = this.requirePermit(input.permitId);
+            this.assertFence(current, input);
+            if (current.ownerMode !== input.ownerMode) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} belongs to ${current.ownerMode}, not ${input.ownerMode}.`, 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT');
+            }
+            if (current.state !== 'gateway-complete-awaiting-apply'
+                || current.upstreamDisposition !== 'accepted') {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} has no accepted apply completion to renew.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            const now = this.now();
+            const deadlineMs = Date.parse(input.deadlineAt);
+            if (!Number.isFinite(deadlineMs)
+                || deadlineMs <= Date.parse(now)
+                || deadlineMs <= Date.parse(current.deadlineAt)) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} renewal deadline is invalid.`, 'SYNC_COORDINATOR_PERMIT_EXPIRED');
+            }
+            const result = this.db.prepare(`
+                UPDATE local_sync_execution_permits
+                SET deadline_at = ?,
+                    last_transition_at = ?
+                WHERE permit_id = ?
+                  AND workspace_id = ?
+                  AND coordinator_generation = ?
+                  AND server_instance_id = ?
+                  AND owner_mode = ?
+                  AND state = 'gateway-complete-awaiting-apply'
+                  AND upstream_disposition = 'accepted'
+            `).run(input.deadlineAt, now, input.permitId, input.workspaceId, input.coordinatorGeneration, input.serverInstanceId, input.ownerMode);
+            if (Number(result?.changes || 0) !== 1) {
+                throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} changed before its renewal committed.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
+            }
+            return this.read(input.permitId);
+        })();
+    }
     completeAcceptedV3Dispatch(input, applyAuthoritativeAndAck) {
         return this.db.transaction(() => {
             const current = this.requirePermit(input.permitId);
@@ -677,19 +733,14 @@ export class LocalSyncExecutionPermitStore {
                 WHERE resolved_at IS NOT NULL
                 ORDER BY resolved_at DESC, obligation_id DESC
             `).all().map(mapObligation);
-            const protectedObligationIds = new Set(resolvedObligations
-                .slice(0, LOCAL_SYNC_PERMIT_RETENTION_SOFT_LIMIT)
-                .map((obligation) => obligation.obligationId));
-            for (const obligation of resolvedObligations) {
-                if (obligation.resolvedAt && obligation.resolvedAt >= cutoff) {
-                    protectedObligationIds.add(obligation.obligationId);
-                }
-            }
+            const obligationAgeDeleteCount = Math.max(0, resolvedObligations.length - LOCAL_SYNC_PERMIT_RETENTION_SOFT_LIMIT);
+            const obligationHardDeleteCount = Math.max(0, resolvedObligations.length - LOCAL_SYNC_OBLIGATION_RETENTION_HARD_LIMIT);
             const obligationCandidates = resolvedObligations
-                .filter((obligation) => (obligation.resolvedAt
-                && obligation.resolvedAt < cutoff
-                && !protectedObligationIds.has(obligation.obligationId)))
+                .slice()
                 .reverse()
+                .filter((obligation, index) => (index < obligationHardDeleteCount
+                || (index < obligationAgeDeleteCount
+                    && Boolean(obligation.resolvedAt && obligation.resolvedAt < cutoff))))
                 .slice(0, boundedDeleteLimit);
             const removeObligation = this.db.prepare(`
                 DELETE FROM local_sync_recovery_obligations
@@ -707,14 +758,7 @@ export class LocalSyncExecutionPermitStore {
                   AND completed_at IS NOT NULL
                 ORDER BY completed_at DESC, permit_id DESC
             `).all().map(mapPermit);
-            const protectedPermitIds = new Set(terminalPermits
-                .slice(0, LOCAL_SYNC_PERMIT_RETENTION_SOFT_LIMIT)
-                .map((permit) => permit.permitId));
-            for (const permit of terminalPermits) {
-                if (permit.completedAt && permit.completedAt >= cutoff) {
-                    protectedPermitIds.add(permit.permitId);
-                }
-            }
+            const protectedPermitIds = new Set();
             const referencedPermitRows = this.db.prepare(`
                 SELECT permit_id
                 FROM local_sync_recovery_obligations
@@ -723,11 +767,15 @@ export class LocalSyncExecutionPermitStore {
                 if (row.permit_id)
                     protectedPermitIds.add(row.permit_id);
             }
+            const permitAgeDeleteCount = Math.max(0, terminalPermits.length - LOCAL_SYNC_PERMIT_RETENTION_SOFT_LIMIT);
+            const permitHardDeleteCount = Math.max(0, terminalPermits.length - LOCAL_SYNC_PERMIT_RETENTION_HARD_LIMIT);
             const permitCandidates = terminalPermits
-                .filter((permit) => (permit.completedAt
-                && permit.completedAt < cutoff
-                && !protectedPermitIds.has(permit.permitId)))
+                .slice()
                 .reverse()
+                .filter((permit, index) => (!protectedPermitIds.has(permit.permitId)
+                && (index < permitHardDeleteCount
+                    || (index < permitAgeDeleteCount
+                        && Boolean(permit.completedAt && permit.completedAt < cutoff)))))
                 .slice(0, boundedDeleteLimit);
             const removePermit = this.db.prepare(`
                 DELETE FROM local_sync_execution_permits

package/dist/sync/coordinator/workspaceSyncTransportGateway.js

@@ -500,10 +500,11 @@ export function workspaceSyncGatewayTimeoutMs(operation) {
     if (operation.type === 'initiative-repair'
         || operation.type === 'combined-repair'
         || operation.type === 'v3-feed-repair'
-        || (operation.type === 'push' && operation.repairMode === true)
-        || (operation.type === 'pull' && operation.repairMode === true)
         || (operation.type === 'v3-feed'
             && (operation.forceRepair === true || Boolean(operation.repairCursor))))
+        return 75_000;
+    if ((operation.type === 'push' && operation.repairMode === true)
+        || (operation.type === 'pull' && operation.repairMode === true))
         return 180_000;
     if (operation.type === 'push'
         || operation.type === 'bootstrap-push')
@@ -638,6 +639,7 @@ const CHANGE_FIELDS = {
     'task-relationship-delete': { allowed: ['op', 'relationship'], required: ['relationship'], objectField: 'relationship' },
     'initiative-upsert': { allowed: ['op', 'initiative'], required: ['initiative'], objectField: 'initiative' },
     'workstream-upsert': { allowed: ['op', 'workstream'], required: ['workstream'], objectField: 'workstream' },
+    'planning-identity-upsert': { allowed: ['op', 'identity'], required: ['identity'], objectField: 'identity' },
     'taxonomy-upsert': { allowed: ['op', 'taxonomies', 'taxonomyState', 'updatedAt', 'durableRevision'], required: ['updatedAt'] },
     'ai-profile-upsert': { allowed: ['op', 'profile'], required: ['profile'], objectField: 'profile' },
     'document-upsert': { allowed: [

package/dist/sync/engine/workspaceSyncEngineRemoteServices.d.ts

@@ -83,6 +83,11 @@ export interface WorkspaceSyncEngineRemoteServices {
         workspaceId: string;
         receipts: readonly WorkspaceSyncEngineRemoteTransferReceipt[];
     }): void | Promise<void>;
+    /** Keeps accepted applying receipts alive until a bounded transfer reaches its atomic commit. */
+    retainTransferReceipts?(input: {
+        workspaceId: string;
+        receipts: readonly WorkspaceSyncEngineRemoteTransferReceipt[];
+    }): void | Promise<void>;
     buildV2ApplyCompletionGroup(input: {
         workspaceId: string;
         previousCursor: string | null;

package/dist/sync/engine/workspaceSyncEngineServerRemoteServices.d.ts

@@ -1,7 +1,7 @@
 import type { LocalSyncExecutionPermitStore } from '../coordinator/localSyncExecutionPermitStore.js';
 import type { WorkspaceSyncTransportGateway } from '../coordinator/workspaceSyncTransportGateway.js';
 import type { WorkspaceSyncEngineRemoteServices } from './workspaceSyncEngineRemoteServices.js';
-type ServerRemotePermitStore = Pick<LocalSyncExecutionPermitStore, 'issueServer' | 'read' | 'acknowledgeNonApplyingCompletion' | 'completeAcceptedPushWithoutEcho' | 'abandonPermit'>;
+type ServerRemotePermitStore = Pick<LocalSyncExecutionPermitStore, 'issueServer' | 'read' | 'acknowledgeNonApplyingCompletion' | 'completeAcceptedPushWithoutEcho' | 'renewAcceptedApplyCompletion' | 'abandonPermit'>;
 type ServerRemoteGateway = Pick<WorkspaceSyncTransportGateway, 'executeServer'>;
 export interface ServerWorkspaceSyncEngineRemoteServicesOptions {
     workspaceId: string;

package/dist/sync/engine/workspaceSyncEngineServerRemoteServices.js

@@ -181,6 +181,7 @@ export function createServerWorkspaceSyncEngineRemoteServices(options) {
             workspaceId: options.workspaceId,
             previousBoundary: input.previousBoundary,
             operationClass,
+            retentionMs: permitDeadlineMs,
         });
         return {
             ...result,
@@ -417,6 +418,20 @@ export function createServerWorkspaceSyncEngineRemoteServices(options) {
                 }
             }
         },
+        retainTransferReceipts: ({ workspaceId, receipts }) => {
+            const metadata = readReceipts(workspaceId, receipts);
+            const retainedAt = now();
+            for (const receipt of metadata) {
+                options.permitStore.renewAcceptedApplyCompletion({
+                    permitId: receipt.permitId,
+                    workspaceId,
+                    coordinatorGeneration: options.coordinatorGeneration,
+                    ownerMode: 'server',
+                    serverInstanceId: options.serverInstanceId,
+                    deadlineAt: new Date(retainedAt.getTime() + receipt.retentionMs).toISOString(),
+                });
+            }
+        },
         buildV2ApplyCompletionGroup: ({ workspaceId, previousCursor, nextCursor, receipts, }) => completionGroup(workspaceId, receipts, v2Boundary(previousCursor), v2Boundary(nextCursor)),
         buildV2PushApplyCompletionGroup: ({ workspaceId, pushBoundary, receipts, }) => completionGroup(workspaceId, receipts, parseWorkspaceSyncEngineV2PushBoundary(pushBoundary), parseWorkspaceSyncEngineV2PushBoundary(pushBoundary)),
         buildV3ApplyCompletionGroup: ({ workspaceId, apply, receipts }) => {

package/dist/sync/engine/workspaceSyncEngineServerRunnerOperations.js

@@ -146,6 +146,20 @@ export function createWorkspaceSyncEngineServerRunnerOperations(options) {
                 transformCheckpointAtTransferBoundary: (boundary) => (transferBoundaryCheckpointTransform(boundary)),
             },
         });
+        const prepareAndDrainRecoveryReplay = async (preparedRecovery) => {
+            let recovery = preparedRecovery
+                ?? await localServices.prepareOutboxRecovery(workspaceId);
+            if (recovery.kind === 'recovery' && recovery.state === 'replay_queued') {
+                const drainResult = await options.drainV3Outbox?.({
+                    beforeTransport: () => undefined,
+                });
+                if (drainResult === 'v2-content-push-required') {
+                    fail('v2-content-push', 'A referenced attachment must be published before durable repair can continue.', 'SYNC_RUNNER_V2_CONTENT_PUSH_REQUIRED');
+                }
+                recovery = await localServices.prepareOutboxRecovery(workspaceId);
+            }
+            return recovery;
+        };
         const ensureReady = options.ensureCloudWorkspaceReadyForSync
             || (async () => {
                 const result = await options.remoteServices.handshakeWorkspace(workspaceId);
@@ -884,8 +898,7 @@ export function createWorkspaceSyncEngineServerRunnerOperations(options) {
                 }
                 if (localRecovery.kind === 'recovery'
                     && localRecovery.state === 'replay_queued') {
-                    await options.drainV3Outbox?.({ beforeTransport: () => undefined });
-                    localRecovery = await localServices.prepareOutboxRecovery(workspaceId);
+                    localRecovery = await prepareAndDrainRecoveryReplay(localRecovery);
                 }
                 if (localRecovery.kind === 'recovery'
                     && localRecovery.state === 'replay_queued') {
@@ -912,7 +925,10 @@ export function createWorkspaceSyncEngineServerRunnerOperations(options) {
                 const continuationInvalid = continuation !== null && (continuation.coordinatorGeneration !== input.coordinatorGeneration
                     || continuation.ownershipFingerprint !== ownershipFingerprint
                     || (recoveryBatchId !== null
-                        && continuation.recoveryBatchId !== recoveryBatchId));
+                        && continuation.recoveryBatchId !== recoveryBatchId)
+                    || (recoveryBatchId !== null
+                        && continuation.kind !== 'v3-combined'
+                        && continuation.kind !== 'v2-reconcile'));
                 if (continuationInvalid || (checkpoint.repairContinuation !== null && !continuation)) {
                     if (checkpoint.pendingV2Push) {
                         await push({
@@ -1030,6 +1046,13 @@ export function createWorkspaceSyncEngineServerRunnerOperations(options) {
                     }
                     continuation = checkpoint.repairContinuation;
                 }
+                if (continuation.recoveryBatchId) {
+                    const postPullRecovery = await prepareAndDrainRecoveryReplay();
+                    if (postPullRecovery.kind === 'recovery'
+                        || Number(options.inspectV3Outbox?.().activeDepth || 0) > 0) {
+                        fail('repair', 'Durable recovery replay must settle before authoritative repair continues.', 'SYNC_RUNNER_RECOVERY_REPLAY_PENDING', RETRY_MAX_DELAY_MS);
+                    }
+                }
                 let pushResult = null;
                 if (continuation.kind === 'final-push') {
                     pushResult = await push({

package/dist/sync/engine/workspaceSyncV2ChangeDispatcher.js

@@ -279,6 +279,7 @@ export function createWorkspaceSyncV2ChangeDispatcher(dependencies) {
                 workspaceId,
                 incomingInitiatives: applyModel.planning.incomingInitiatives,
                 incomingWorkstreams: applyModel.planning.incomingWorkstreams,
+                incomingIdentities: applyModel.planning.incomingIdentities,
                 recordSyncDiagnostic,
                 ...(options.coexistenceDirection ? {
                     coexistenceDirection: options.coexistenceDirection,
@@ -722,6 +723,7 @@ export function createWorkspaceSyncV2ChangeDispatcher(dependencies) {
                     workspaceId,
                     incomingInitiatives: applyModel.planning.incomingInitiatives,
                     incomingWorkstreams: applyModel.planning.incomingWorkstreams,
+                    incomingIdentities: applyModel.planning.incomingIdentities,
                     recordSyncDiagnostic,
                     ...(options.coexistenceDirection ? {
                         coexistenceDirection: options.coexistenceDirection,

package/dist/sync/syncApplyHandlers.d.ts

@@ -1,6 +1,6 @@
 import type { TaskforceCore, TaskforceSyncCapable } from '../core/Taskforce.js';
 import type { DeletedTaskDetails, DeletedTaskSource, TaskRelationshipRecord } from '../core/Taskforce.js';
-import type { WorkspaceSyncAiProfileSnapshot, WorkspaceSyncAgentConversationSnapshot, WorkspaceSyncAgentRoleSnapshot, WorkspaceSyncAnnotatedAttachmentSessionSnapshot, WorkspaceSyncChange, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncDurableTaskRevision, WorkspaceSyncDurableTaxonomyRevision, WorkspaceSyncEntityEventSnapshot, WorkspaceSyncInitiativeSnapshot, WorkspaceSyncTaskforceAgentSnapshot, WorkspaceSyncTaskforceAgentSkillSnapshot, WorkspaceSyncTaskSnapshot, WorkspaceSyncWorkspaceMemberSnapshot, WorkspaceSyncWorkstreamSnapshot } from './workspaceSyncModel.js';
+import type { WorkspaceSyncAiProfileSnapshot, WorkspaceSyncAgentConversationSnapshot, WorkspaceSyncAgentRoleSnapshot, WorkspaceSyncAnnotatedAttachmentSessionSnapshot, WorkspaceSyncChange, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncDurableTaskRevision, WorkspaceSyncDurableTaxonomyRevision, WorkspaceSyncEntityEventSnapshot, WorkspaceSyncInitiativeSnapshot, WorkspaceSyncPlanningIdentitySnapshot, WorkspaceSyncTaskforceAgentSnapshot, WorkspaceSyncTaskforceAgentSkillSnapshot, WorkspaceSyncTaskSnapshot, WorkspaceSyncWorkspaceMemberSnapshot, WorkspaceSyncWorkstreamSnapshot } from './workspaceSyncModel.js';
 import type { BinaryAssetSyncPayload, DocumentSyncPayload } from './contentSyncPayload.js';
 import type { WorkspaceTaxonomyState } from '../shared/taxonomyState.js';
 import { WorkspaceSyncDurabilityStore } from './v3/syncDurabilityStore.js';
@@ -55,6 +55,7 @@ export interface WorkspaceSyncIncomingApplyModel {
         incomingTaxonomyDurableRevision: WorkspaceSyncDurableTaxonomyRevision | null;
         incomingInitiatives: Map<string, WorkspaceSyncInitiativeSnapshot>;
         incomingWorkstreams: Map<string, WorkspaceSyncWorkstreamSnapshot>;
+        incomingIdentities: Map<string, WorkspaceSyncPlanningIdentitySnapshot>;
     };
     profiles: {
         incomingAiProfiles: Map<string, WorkspaceSyncAiProfileSnapshot>;
@@ -163,6 +164,7 @@ export declare function applyPlanningSyncChanges(input: {
     workspaceId: string;
     incomingInitiatives: Map<string, WorkspaceSyncInitiativeSnapshot>;
     incomingWorkstreams: Map<string, WorkspaceSyncWorkstreamSnapshot>;
+    incomingIdentities?: Map<string, WorkspaceSyncPlanningIdentitySnapshot>;
     recordSyncDiagnostic: RecordSyncDiagnostic;
     coexistenceDirection?: TaskMetadataCoexistenceDirection;
     assertedActiveV3InitiativeIds?: ReadonlySet<string>;

package/dist/sync/syncApplyHandlers.js

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash } from 'crypto';
+import { assertPlanningIdentityColor, assertPlanningIdentityIcon } from '../shared/planningIdentity.js';
 import { parseAiProfileColorSource } from '../shared/aiProfileColors.js';
 import { normalizeBinaryAssetDeleteSyncPayload, normalizeBinaryAssetSyncPayload, normalizeDocumentDeleteSyncPayload, normalizeDocumentSyncPayload, } from './contentSyncPayload.js';
 import { normalizeAiProfileSyncPayload, normalizeAgentConversationSyncPayload, normalizeAgentRoleSyncPayload, normalizeAnnotatedAttachmentSessionSyncPayload, normalizeDeleteSyncPayload, normalizeDocumentReviewCommentSyncPayload, normalizeDocumentReviewSessionSyncPayload, normalizeTaskforceAgentSkillSyncPayload, normalizeTaskforceAgentSyncPayload, } from './collaborationSyncPayload.js';
@@ -32,6 +33,7 @@ function createIncomingApplyModel() {
             incomingTaxonomyDurableRevision: null,
             incomingInitiatives: new Map(),
             incomingWorkstreams: new Map(),
+            incomingIdentities: new Map(),
         },
         profiles: {
             incomingAiProfiles: new Map(),
@@ -68,6 +70,7 @@ function shouldSkipTaskClassification(op) {
         || op === 'task-relationship-delete'
         || op === 'initiative-upsert'
         || op === 'workstream-upsert'
+        || op === 'planning-identity-upsert'
         || op === 'document-upsert'
         || op === 'document-delete'
         || op === 'asset-upsert'
@@ -185,6 +188,26 @@ export function classifyWorkspaceSyncChanges(input) {
                 model.planning.incomingWorkstreams.set(workstream.id, workstream);
             continue;
         }
+        if (op === 'planning-identity-upsert') {
+            const value = raw.identity;
+            const entityType = value?.entityType === 'initiative' || value?.entityType === 'workstream'
+                ? value.entityType
+                : null;
+            const entityId = String(value?.entityId || '').trim();
+            const updatedAt = String(value?.updatedAt || raw.updatedAt || raw.watermark || '').trim();
+            if (!entityType || !entityId || !Number.isFinite(Date.parse(updatedAt))) {
+                throw new Error('Planning identity sync payload is invalid.');
+            }
+            const identity = {
+                entityType,
+                entityId,
+                icon: assertPlanningIdentityIcon(value?.icon),
+                color: assertPlanningIdentityColor(value?.color),
+                updatedAt,
+            };
+            model.planning.incomingIdentities.set(`${entityType}:${entityId}`, identity);
+            continue;
+        }
         if (op === 'ai-profile-upsert') {
             const profile = normalizeAiProfileSyncPayload(raw.profile, workspaceId, normalizeIncomingAiProfileSurfaceType, normalizeIncomingAiProfileSeatScope, 'apply.aiProfileUpsert');
             const profileId = String(profile?.id || '').trim();
@@ -690,6 +713,12 @@ export function applyPlanningSyncChanges(input) {
             }
         }
     }
+    for (const identity of input.incomingIdentities?.values() || []) {
+        const applied = core.applyPlanningEntityIdentityForSync(identity, workspaceId);
+        if (!applied) {
+            throw new Error(`Planning identity parent is missing: ${identity.entityType}:${identity.entityId}`);
+        }
+    }
 }
 export function applyTaxonomySyncChanges(input) {
     const hasTaxonomy = Boolean(input.incomingTaxonomyState) || Array.isArray(input.incomingTaxonomies);

package/dist/sync/syncService.js

@@ -217,6 +217,7 @@ function workspacePushChangeStableIdentity(change) {
         case 'task-relationship-delete': return `${change.op}:${change.relationship.id}`;
         case 'initiative-upsert': return `${change.op}:${change.initiative.id}`;
         case 'workstream-upsert': return `${change.op}:${change.workstream.id}`;
+        case 'planning-identity-upsert': return `${change.op}:${change.identity.entityType}:${change.identity.entityId}`;
         case 'taxonomy-upsert': return change.op;
         case 'ai-profile-upsert': return `${change.op}:${change.profile.id}`;
         case 'document-upsert':
@@ -284,6 +285,8 @@ function resolveWorkspacePushPhase(change) {
             return 0;
         case 'workstream-upsert':
             return 1;
+        case 'planning-identity-upsert':
+            return 2;
         case 'upsert':
             return 2;
         case 'document-upsert':
@@ -689,6 +692,12 @@ export async function runWorkspacePushSyncService(input) {
                 completedChangeCount += plainBatchChanges.length;
                 continue;
             }
+            if (pushTransferReceipts.length > 0) {
+                await remoteServices.retainTransferReceipts?.({
+                    workspaceId: input.workspaceId,
+                    receipts: pushTransferReceipts,
+                });
+            }
             const sendPush = async () => {
                 const requestStartedAtMs = Date.now();
                 const result = await remoteServices.pushWorkspaceChanges({

package/dist/sync/taskSyncPayload.d.ts

@@ -25,6 +25,7 @@ export interface TaskSyncPayload {
     referenceNumber?: number | null;
     comments?: Comment[];
     attachments?: Array<string | AttachmentItem>;
+    cardCoverAssetId?: string | null;
     checklistItems?: ChecklistItem[];
 }
 export declare function serializeTaskForSync(task: Partial<TaskItem> | null | undefined): TaskSyncPayload;

package/dist/sync/taskSyncPayload.js

@@ -64,6 +64,7 @@ function cloneChecklistItems(value) {
 }
 export function serializeTaskForSync(task) {
     const source = task && typeof task === 'object' ? task : {};
+    const hasCardCoverAssetId = Object.prototype.hasOwnProperty.call(source, 'cardCoverAssetId');
     return {
         id: String(source.id || '').trim(),
         title: String(source.title || '').trim(),
@@ -89,6 +90,9 @@ export function serializeTaskForSync(task) {
         referenceNumber: toOptionalInteger(source.referenceNumber, { min: 1, nullable: true }),
         comments: cloneComments(source.comments),
         attachments: cloneAttachments(source.attachments),
+        ...(hasCardCoverAssetId
+            ? { cardCoverAssetId: toNullableString(source.cardCoverAssetId) }
+            : {}),
         checklistItems: cloneChecklistItems(source.checklistItems),
     };
 }
@@ -102,6 +106,7 @@ export function normalizeTaskSyncPayload(raw) {
     return serializeTaskForSync(source);
 }
 export function taskSyncPayloadToCoreTask(task) {
+    const hasCardCoverAssetId = Object.prototype.hasOwnProperty.call(task, 'cardCoverAssetId');
     return {
         id: task.id,
         title: task.title,
@@ -127,6 +132,7 @@ export function taskSyncPayloadToCoreTask(task) {
         referenceNumber: task.referenceNumber ?? undefined,
         comments: task.comments,
         attachments: task.attachments,
+        ...(hasCardCoverAssetId ? { cardCoverAssetId: task.cardCoverAssetId } : {}),
         checklistItems: task.checklistItems
     };
 }

package/dist/sync/v3/durableTaskAttachmentLinksMutationRouter.d.ts

@@ -40,6 +40,7 @@ export declare function createDurableTaskAttachmentLinksMutationRouter(input: {
     replace(args: {
         taskId: string;
         links: readonly WorkspaceSyncV3TaskAttachmentLink[];
+        cardCoverAssetId?: string | null;
     }): {
         state: "pending" | "committed";
         route: "local-outbox" | "cloud-acceptance";

package/dist/sync/v3/durableTaskAttachmentLinksMutationRouter.js

@@ -4,6 +4,7 @@ import { enqueueLocalTaskAttachmentLinksMutation, } from './localTaskAttachmentL
 import { DurableTaskAttachmentLinksMutationError, runDurableTaskAttachmentLinksReplace, } from './taskAttachmentLinksMutationService.js';
 import { WorkspaceSyncDurabilityStore, WorkspaceSyncEntityBusyError } from './syncDurabilityStore.js';
 import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { resolveTaskCardCoverAssetIdForLinks } from '../../core/TaskAttachmentLinksDurableMutationService.js';
 const OPERATION_LEASE_MS = 30_000;
 function enabled(value) {
     return /^(1|true|on|yes)$/i.test(String(value || '').trim());
@@ -93,6 +94,22 @@ export function createDurableTaskAttachmentLinksMutationRouter(input) {
             catch (error) {
                 throw new DurableTaskAttachmentLinksMutationError(error instanceof Error ? error.message : 'Task attachment links are invalid.', 'TASK_ATTACHMENT_LINKS_INVALID', 400);
             }
+            const currentTask = input.core.getTask(taskId, workspaceId);
+            if (!currentTask)
+                throw new DurableTaskAttachmentLinksMutationError('Task not found.', 'TASK_NOT_FOUND', 404);
+            let cardCoverAssetId;
+            try {
+                cardCoverAssetId = resolveTaskCardCoverAssetIdForLinks({
+                    currentCardCoverAssetId: currentTask.cardCoverAssetId,
+                    ...(Object.prototype.hasOwnProperty.call(args, 'cardCoverAssetId')
+                        ? { requestedCardCoverAssetId: args.cardCoverAssetId }
+                        : {}),
+                    links,
+                });
+            }
+            catch (error) {
+                throw new DurableTaskAttachmentLinksMutationError(error instanceof Error ? error.message : 'Task card cover is invalid.', 'TASK_ATTACHMENT_LINKS_INVALID', Number(error?.statusCode) || 400);
+            }
             const acceptedAt = now();
             const acceptedAtIso = acceptedAt.toISOString();
             const operationId = operationIdRequired(input.operationId);
@@ -123,7 +140,8 @@ export function createDurableTaskAttachmentLinksMutationRouter(input) {
                     catch {
                         throw new DurableTaskAttachmentLinksMutationError('Captured task attachment-link payload is invalid.', 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT', 409);
                     }
-                    if (canonicalWorkspaceSyncJson(frozen) !== canonicalWorkspaceSyncJson(links)) {
+                    if (canonicalWorkspaceSyncJson(frozen) !== canonicalWorkspaceSyncJson(links)
+                        || String(payload.cardCoverAssetId || '') !== String(cardCoverAssetId || '')) {
                         throw new DurableTaskAttachmentLinksMutationError('Operation identity is assigned to different task attachment links.', 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT', 409);
                     }
                     const task = input.core.getTask(taskId, workspaceId);
@@ -138,7 +156,7 @@ export function createDurableTaskAttachmentLinksMutationRouter(input) {
                 let result;
                 try {
                     result = enqueueLocalTaskAttachmentLinksMutation({
-                        store, core: serviceCore, identity, taskId, links, now: acceptedAtIso,
+                        store, core: serviceCore, identity, taskId, links, cardCoverAssetId, now: acceptedAtIso,
                         actorRef, onPostCommitError: input.onPostCommitError,
                         requireV3CombinedOwnership: persistedOwnershipChecked,
                     });
@@ -182,7 +200,7 @@ export function createDurableTaskAttachmentLinksMutationRouter(input) {
                 });
             }
             const result = runDurableTaskAttachmentLinksReplace({
-                store, core: serviceCore, tenantId, workspaceId, clientId, operationId, taskId, links,
+                store, core: serviceCore, tenantId, workspaceId, clientId, operationId, taskId, links, cardCoverAssetId,
                 baseEntityRevision: coordinates.entityRevision, baseLifecycleRevision: coordinates.lifecycleRevision,
                 now: acceptedAtIso, leaseExpiresAt: new Date(acceptedAt.getTime() + OPERATION_LEASE_MS).toISOString(),
                 actorRef, onPostCommitError: input.onPostCommitError,

package/dist/sync/v3/durableTaskHttpBulkMutationRouter.js

@@ -245,15 +245,22 @@ export function createDurableTaskHttpBulkMutationRouter(input) {
                         if (hasAttachments && !Array.isArray(item.fields.attachments)) {
                             throw new TaskforceRuleError('attachments must be an array.', 400, 'TASK_ATTACHMENT_LINKS_INVALID');
                         }
-                        const attachmentOperationId = hasAttachments
+                        const hasCardCover = Object.prototype.hasOwnProperty.call(item.fields, 'cardCoverAssetId');
+                        if (hasCardCover && item.fields.cardCoverAssetId !== null
+                            && (typeof item.fields.cardCoverAssetId !== 'string' || !item.fields.cardCoverAssetId.trim())) {
+                            throw new TaskforceRuleError('cardCoverAssetId must be a non-empty string or null.', 400, 'TASK_CARD_COVER_INVALID');
+                        }
+                        const attachmentOperationId = hasAttachments || hasCardCover
                             ? input.deriveChildOperationId('bulk-update-fields-attachments', item.index, item.id)
                             : '';
-                        const attachmentLinks = hasAttachments
+                        const attachmentLinks = hasAttachments || hasCardCover
                             ? input.createAttachmentLinksRouter(attachmentOperationId)
                             : null;
                         const durableAttachmentLinks = attachmentLinks?.enabled === true;
                         const normalizedAttachmentLinks = durableAttachmentLinks
-                            ? normalizeAttachmentLinks(item.fields.attachments)
+                            ? normalizeAttachmentLinks(hasAttachments
+                                ? item.fields.attachments
+                                : input.core.getTask(item.id, input.workspaceId)?.attachments || [])
                             : [];
                         const checklistOperationId = hasChecklist
                             ? input.deriveChildOperationId('bulk-update-fields-checklist', item.index, item.id)
@@ -262,7 +269,8 @@ export function createDurableTaskHttpBulkMutationRouter(input) {
                         const durableChecklist = checklist?.enabled === true;
                         const rootFields = durableChecklist || durableAttachmentLinks
                             ? Object.fromEntries(Object.entries(item.fields).filter(([key]) => (!(durableChecklist && key === 'checklistItems')
-                                && !(durableAttachmentLinks && key === 'attachments'))))
+                                && !(durableAttachmentLinks && key === 'attachments')
+                                && !(durableAttachmentLinks && key === 'cardCoverAssetId'))))
                             : item.fields;
                         let updated = input.core.getTask(item.id, input.workspaceId);
                         if (Object.keys(rootFields).length > 0) {
@@ -299,6 +307,11 @@ export function createDurableTaskHttpBulkMutationRouter(input) {
                             updated = batch.runChild(() => attachmentLinks.replace({
                                 taskId: item.id,
                                 links: normalizedAttachmentLinks,
+                                ...(hasCardCover ? {
+                                    cardCoverAssetId: item.fields.cardCoverAssetId === null
+                                        ? null
+                                        : String(item.fields.cardCoverAssetId).trim(),
+                                } : {}),
                             }).task);
                         }
                         if (updated)

package/dist/sync/v3/localInitiativeOutboxService.js

@@ -294,8 +294,9 @@ function validateActivitySemantics(input) {
     const authoritativeAttachmentLinks = validateCanonicalPlanningAttachmentLinks(input.authoritative.attachments);
     const comparableExpectedDetails = normalizePlanningActivityDetailsForComparison(expectedDetails, input.record.mutationKind, authoritativeAttachmentLinks);
     const comparableAuthoritativeDetails = normalizePlanningActivityDetailsForComparison((input.activity.details || {}), input.record.mutationKind, authoritativeAttachmentLinks);
-    if (fingerprintWorkspaceSyncPayload(comparableExpectedDetails)
-        !== fingerprintWorkspaceSyncPayload(comparableAuthoritativeDetails)) {
+    if (!input.boundedAttachmentRebase
+        && fingerprintWorkspaceSyncPayload(comparableExpectedDetails)
+            !== fingerprintWorkspaceSyncPayload(comparableAuthoritativeDetails)) {
         throw new LocalAuthoritativeInitiativeError('Authoritative initiative activity details differ from the captured mutation.');
     }
 }
@@ -437,6 +438,7 @@ export function applyAuthoritativeInitiativeAndAck(input) {
         payload: payload,
         authoritative: initiative,
         activity,
+        boundedAttachmentRebase,
     });
     const revision = validateInitiativeActivityAuthoritativeRevision({
         response: response,

package/dist/sync/v3/localOutboxDispatcher.js

@@ -279,7 +279,11 @@ export async function dispatchLocalOutboxBatch(input) {
             const details = errorDetails(result.data, `WORKSPACE_SYNC_TRANSPORT_${result.status || 'NETWORK'}`, 'Workspace sync delivery failed.');
             const stableErrorCode = result.status === 401 ? 'WORKSPACE_SYNC_TRANSPORT_401' : details.code;
             const contentPushRequired = result.status === 425
-                && stableErrorCode === 'TASK_ATTACHMENT_ASSET_NOT_READY';
+                && [
+                    'TASK_ATTACHMENT_ASSET_NOT_READY',
+                    'WORKSTREAM_ATTACHMENT_NOT_READY',
+                    'INITIATIVE_ATTACHMENT_NOT_READY',
+                ].includes(stableErrorCode);
             const inProgressDelay = operationRetryAt(result.data, now().getTime());
             const cloudV3Disabled = result.status === 404 && isCloudV3Disabled(record, result.data);
             // A first metadata edit may dispatch before legacy reconciliation has

package/dist/sync/v3/localTaskAttachmentLinksOutboxHandler.js

@@ -17,8 +17,13 @@ export function buildTaskAttachmentLinksEnvelope(record) {
     }
     const source = payload;
     if (!Object.prototype.hasOwnProperty.call(source, 'links')
-        || Object.keys(source).some((key) => key !== 'links' && key !== 'originActor')) {
-        throw new Error('Local task attachment-link outbox payload must contain links and optional originActor.');
+        || Object.keys(source).some((key) => !['links', 'cardCoverAssetId', 'originActor'].includes(key))) {
+        throw new Error('Local task attachment-link outbox payload must contain links and optional card cover metadata.');
+    }
+    const hasCardCoverAssetId = Object.prototype.hasOwnProperty.call(source, 'cardCoverAssetId');
+    if (hasCardCoverAssetId && source.cardCoverAssetId !== null
+        && (typeof source.cardCoverAssetId !== 'string' || !source.cardCoverAssetId.trim())) {
+        throw new Error('Local task attachment-link card cover must be a non-empty string or null.');
     }
     const aggregate = validateWorkspaceSyncV3TaskAttachmentLinksPayload({ taskId: record.entityId, links: source.links });
     return {
@@ -31,6 +36,11 @@ export function buildTaskAttachmentLinksEnvelope(record) {
             baseEntityRevision: record.baseEntityRevision, baseLifecycleRevision: '0',
             payload: {
                 links: aggregate.links,
+                ...(hasCardCoverAssetId ? {
+                    cardCoverAssetId: source.cardCoverAssetId === null
+                        ? null
+                        : String(source.cardCoverAssetId).trim(),
+                } : {}),
                 ...(source.originActor !== undefined
                     ? { originActor: parseWorkspaceSyncV3OriginActor(source.originActor) }
                     : {}),